Merge pull request #109 from vimeo/dev

Release 2.2.0

CHANGELOG.md

@@ -1,6 +1,11 @@
 Change Log
 ==========
 
+Version 2.2.0 *(2017-05-30)*
+----------------------------
+- Added support for private member variables in Java (leveraging getters/setters).
+- Added support for models written in Kotlin.
+
 Version 2.1.4 *(2017-05-10)*
 ----------------------------
 - Added compiler support for all Java language versions.

README.md

@@ -45,13 +45,14 @@ buildscript {
 apply plugin: 'net.ltgt.apt'
 
 dependencies {
-    compile 'com.vimeo.stag:stag-library:2.1.4'
-    apt 'com.vimeo.stag:stag-library-compiler:2.1.4'
+    compile 'com.vimeo.stag:stag-library:2.2.0'
+    apt 'com.vimeo.stag:stag-library-compiler:2.2.0'
 }
 
 // Optional annotation processor arguments (see below)
 apt {
     arguments {
+        stagAssumeHungarianNotation true
         stagGeneratedPackageName "com.vimeo.sample.stag.generated"
         stagDebug true
     }
@@ -62,8 +63,8 @@ apt {
 
 ```groovy
 dependencies {
-    compile 'com.vimeo.stag:stag-library:2.1.4'
-    annotationProcessor 'com.vimeo.stag:stag-library-compiler:2.1.4'
+    compile 'com.vimeo.stag:stag-library:2.2.0'
+    annotationProcessor 'com.vimeo.stag:stag-library-compiler:2.2.0'
 }
 
 android {
@@ -74,8 +75,9 @@ android {
         javaCompileOptions {
             annotationProcessorOptions {
                 arguments = [
-                    stagGeneratedPackageName: 'com.vimeo.sample.stag.generated',
-                    stagDebug               : 'true'
+                    stagAssumeHungarianNotation: 'true'
+                    stagGeneratedPackageName   : 'com.vimeo.sample.stag.generated',
+                    stagDebug                  : 'true'
                 ]
             }
         }
@@ -89,7 +91,11 @@ android {
  by passing it as an argument to the apt compiler.
  - `stagDebug`: Turn on debugging in Stag. This will cause Stag to spit out a lot of output into the gradle console.
  This can aid you in figuring out what class is giving you trouble, if the exception gradle prints out
- isn't sufficient.
+ isn't sufficient. Default is false.
+ - `stagAssumeHungarianNotation`: If your Java member variables are private and Stag needs to use setters and getters to access the field,
+ Stag will look for members named `set[variable_name]` and `get[variable_name]`. If your member variables are named using Hungarian notation,
+ then you will need to pass true to this parameter so that for a field named `mField`, Stag will look for `setField` and `getField` instead
+ of `setMField` and `getMField`. Default is false.
 
 ## Features
 
@@ -118,7 +124,16 @@ Last but not the least, Stag is almost in parity with GSON.
 
 ## Stag Rules
 
-1. Make sure the member variables of your model class are not private (should be public, protected, or package-local visibility)
+1. Make sure that any private member variables have setters/getters following these naming rules:
+    ```java
+    private String myString;
+
+    public String getMyString() { ... }
+
+    public void setMyString(String parameter) { ... }
+    ```
+    Java setters and getters must have `protected`, `public`, or package local visibility. If you don't want to use setters and getters, make sure your member variables have `protected`, `public`, or package local visibility.
+    If working with Kotlin, currently, you must make sure your getters all have `public` visibility. Because stag generates Java code, the only way it knows how to access the Kotlin fields is if the setters and getters are public. By default, the visibility set on a Kotlin member variable is also applied to its setters and getters.
 2. Make sure your model class is not private and has a zero argument non-private constructor
 3. Annotate the classes with `@UseStag` annotation. This will process all the member variables of the class, which makes it easy to use.
 4. Use the `@SerializedName("key")` annotation to give the variables a different JSON name. (same as GSON)
@@ -130,23 +145,30 @@ See the [example below](#example) or the [sample app](sample) to get more info o
 
 ## Example
 
+#### Java
 ```java
 @UseStag
 public class Deer {
+
+    // Private fields require getters and setters
     @SerializedName("name")
-    String mName;    // mName = json value with key "name"
+    private String name;    // name = json value with key "name"
 
     @SerializedName("species")
-    String mSpecies; // mSpecies = json value with key "species"
+    String species; // species = json value with key "species"
 
     @SerializedName("age")
-    int mAge;        // mAge = json value with key "age"
+    int age;        // age = json value with key "age"
 
     @SerializedName("points")
-    int mPoints;     // mPoints = json value with key "points"
+    int points;     // points = json value with key "points"
 
     @SerializedName("weight")
-    float mWeight;   // mWeight = json value with key "weight"
+    float weight;   // weight = json value with key "weight"
+
+    public String getName() { return name; }
+
+    public void setName(String name) { this.name = name; }
 }
 
 @UseStag
@@ -160,7 +182,44 @@ public class Herd {
 
     Map<String, Deer> data_map;  // data_map = json value with key "data_map"
 }
+```
+
+#### Kotlin
+```kotlin
+@UseStag
+class Deer {
 
+    @SerializedName("name")
+    var name: String? = null    // name = json value with key "name"
+
+    @SerializedName("species")
+    var species: String? = null // species = json value with key "species"
+
+    @SerializedName("age")
+    var age: Int = 0        // age = json value with key "age"
+
+    @SerializedName("points")
+    var points: Int = 0     // points = json value with key "points"
+
+    @SerializedName("weight")
+    var weight: Float = 0.toFloat()   // weight = json value with key "weight"
+}
+
+@UseStag
+class Herd {
+
+    // non null fields will be honored buy throwing an exception if the field is null
+    @SerializedName("data_list")
+    var data: ArrayList<Deer> = ArrayList()     // data = json value with key "data_list"
+
+    var data_list_copy: List<Deer>? = null   // data_list_copy = json value with key "data_list_copy"
+
+    var data_map: Map<String, Deer>? = null  // data_map = json value with key "data_map"
+}
+```
+
+#### Consuming Model in Java
+```java
 /**
  * The class where you receive JSON 
  * containing a list of Deer objects.
@@ -176,12 +235,13 @@ MyParsingClass {
         return gson.fromJson(json, Herd.class);
     }
 }
-
 ```
 
 ## Future Enhancements
 
 - Add an option to absorb parsing errors rather than crashing and halting parsing (default gson behavior)
+- Support `internal` visibility in Kotlin code
+- Generate Kotlin code for Kotlin models
 
 ## Development
 ```sh

build.gradle

@@ -1,12 +1,14 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 buildscript {
+    ext.kotlin_version = '1.1.2-3'
     repositories {
         jcenter()
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:2.3.1'
+        classpath 'com.android.tools.build:gradle:2.3.2'
         classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.7'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
 
@@ -27,5 +29,5 @@ allprojects {
 
 subprojects {
     group = 'com.vimeo.stag'
-    version = '2.1.4'
+    version = '2.2.0'
 }

fastlane/Fastfile

@@ -39,12 +39,13 @@ platform :android do
     "stag-library/build/test-results/test/*.xml",
     "stag-library-compiler/build/test-results/test/*.xml",
     "sample-java-model/build/test-results/test/*.xml",
+    "sample-kotlin-model/build/test-results/testDebugUnitTest/*.xml",
     "sample/build/test-results/testDebugUnitTest/*.xml",
     "sample-model/build/test-results/testDebugUnitTest/*.xml"
   ]
   begin
     gradle(
-      task: "stag-library:test stag-library-compiler:test sample:test sample-model:test sample-java-model:test sample:build"
+      task: "sample:build stag-library:test stag-library-compiler:test sample:test sample-model:test sample-java-model:test sample-kotlin-model:test"
     )
   rescue => error
   begin

sample-java-model/build.gradle

@@ -1,9 +1,11 @@
 apply plugin: 'java'
 
 dependencies {
-    compile project(':stag-library')
     compile 'com.google.code.gson:gson:2.8.0'
+
+    compile project(':stag-library')
     compileOnly project(':stag-library-compiler')
+
     testCompile 'junit:junit:4.12'
 }
 
@@ -12,8 +14,9 @@ gradle.projectsEvaluated {
         sourceCompatibility = '1.7'
         targetCompatibility = '1.7'
         options.compilerArgs << "-Xlint:all,-deprecation,-serial,-processing,-options" << "-Werror" \
-                << "-AstagGeneratedPackageName=com.vimeo.sample_java_model.stag.generated" \
-                << "-AstagDebug=true"
+                 << "-AstagGeneratedPackageName=com.vimeo.sample_java_model.stag.generated" \
+                 << "-AstagDebug=true" \
+                 << "-AstagAssumeHungarianNotation=true"
         options.setIncremental true
     }
 }

sample-java-model/src/main/java/com/vimeo/sample_java_model/NativeJavaModel.java

@@ -5,29 +5,77 @@
 @UseStag
 public class NativeJavaModel {
 
-    String topLevel;
+    private String mTopLevel;
+
+    public String getTopLevel() {
+        return mTopLevel;
+    }
+
+    public void setTopLevel(String mTopLevel) {
+        this.mTopLevel = mTopLevel;
+    }
 
     @UseStag
     public static class Nested {
-        String nested;
+        private String mNested;
+
+        public String getNested() {
+            return mNested;
+        }
+
+        public void setNested(String mNested) {
+            this.mNested = mNested;
+        }
     }
 
     public static class NestedWithoutAnnotation {
-        String nestedWithoutAnnotation;
+        private String mNestedWithoutAnnotation;
+
+        public String getNestedWithoutAnnotation() {
+            return mNestedWithoutAnnotation;
+        }
+
+        public void setNestedWithoutAnnotation(String mNestedWithoutAnnotation) {
+            this.mNestedWithoutAnnotation = mNestedWithoutAnnotation;
+        }
     }
 
     @UseStag
     public static class NestedExtension extends NativeJavaModel {
-        String nestedExtension;
+        private String mNestedExtension;
+
+        public String getNestedExtension() {
+            return mNestedExtension;
+        }
+
+        public void setNestedExtension(String mNestedExtension) {
+            this.mNestedExtension = mNestedExtension;
+        }
     }
 
     public static class NestedExtensionWithoutAnnotation extends NativeJavaModel {
-        String nestedExtensionWithoutAnnotation;
+        private String mNestedExtensionWithoutAnnotation;
+
+        public String getNestedExtensionWithoutAnnotation() {
+            return mNestedExtensionWithoutAnnotation;
+        }
+
+        public void setNestedExtensionWithoutAnnotation(String mNestedExtensionWithoutAnnotation) {
+            this.mNestedExtensionWithoutAnnotation = mNestedExtensionWithoutAnnotation;
+        }
     }
 
     @UseStag
     public static class NestedExtensionFromNoAnnotation extends NestedWithoutAnnotation {
-        String nestedExtensionFromNoAnnotation;
+        private String mNestedExtensionFromNoAnnotation;
+
+        public String getNestedExtensionFromNoAnnotation() {
+            return mNestedExtensionFromNoAnnotation;
+        }
+
+        public void setNestedExtensionFromNoAnnotation(String mNestedExtensionFromNoAnnotation) {
+            this.mNestedExtensionFromNoAnnotation = mNestedExtensionFromNoAnnotation;
+        }
     }
 
 }

sample-java-model/src/main/java/com/vimeo/sample_java_model/NativeJavaModelExtension.java

@@ -9,6 +9,13 @@
 @UseStag
 public class NativeJavaModelExtension extends NativeJavaModel {
 
-    String additionalField;
+    private String mAdditionalField;
 
+    public String getAdditionalField() {
+        return mAdditionalField;
+    }
+
+    public void setAdditionalField(String additionalField) {
+        this.mAdditionalField = additionalField;
+    }
 }

sample-java-model/src/main/java/com/vimeo/sample_java_model/NativeJavaModelExtensionWithoutAnnotation.java

@@ -6,6 +6,13 @@
  */
 public class NativeJavaModelExtensionWithoutAnnotation extends NativeJavaModel {
 
-    String additionalField2;
+    private String mAdditionalField2;
 
+    public String getAdditionalField2() {
+        return mAdditionalField2;
+    }
+
+    public void setAdditionalField2(String mAdditionalField2) {
+        this.mAdditionalField2 = mAdditionalField2;
+    }
 }