Gson Path
An annotation processor library which generates gson type adapters at compile time which also use basic JsonPath functionality.
Benefits
The benefits of this library are as follows:
Statically generated Gson Type Adapters
By statically generating Gson Type Adapters, the majority of reflection used by the Gson library can be removed. This greatly improves performance and removes code obfuscation issues.
JsonPath syntax
JsonPath syntax can be used to reduce the number of POJOs required to parse a JSON file. See the example section for more details.
This allows for easier integration with other libraries which rely on a flat class structure (such as DBFlow).
POJO immutability via interfaces
You are given the option of using immutable POJOs based off annotated interfaces.
These POJOs are similar to AutoValue, however you do not need to reference the concrete implementation as the Type Adapter creates it on your behalf.
See the interfaces guide for further details.
JsonPath - Path Substitutions
You can reduce the amount of repetition when creating POJOs using Path Substitutions by using straightforward string replacement functionality within the AutoGsonAdapter
annotation.
See the path substitution guide for further details.
Optional client side validation
Add optional client side validation to your json using @Nullable
and NonNull
annotations to add mandatory field constraints.
The client side valiation can also be enhanced through extensions. These extensions are separate annotation processors that register to be notified whenever a field with a specific annotation is encountered.
Notable extensions
Android Support Annotation validation
Example
Given the following JSON:
{
"person": {
"names": {
"first": "Lachlan",
"last": "McKee"
}
}
}
We can deserialize the content with a single class by using Gson Path. The following class demonstrates the annotations required to create a type adapter which can correctly read the content.
@AutoGsonAdapter(rootField = "person.names")
public class PersonModel {
@SerializedName("first")
String firstName;
@SerializedName("last")
String lastName;
}
We could also write it as follows (to reduce the number of annotations required):
@AutoGsonAdapter(rootField = "person.names")
public class PersonModel {
String first;
String last;
}
Setup
The following steps are required to use the generated TypeAdapters
within your project.
AutoGsonAdapterFactory
Create a type adapter factory by annotating an interface as follows:
package com.example;
@AutoGsonAdapterFactory
public interface ExampleGsonTypeFactory extends TypeAdapterFactory {
}
Gson Path can be used across multiple modules by defining a factory within each.
Note: Only one @AutoGsonAdapterFactory
annotation may be used per module/project. If you do this accidentally, the annotation processor will raise a helpful error.
AutoGsonAdapter
Create any number of type adapters by annotating a class or interface as follows:
package com.example;
@AutoGsonAdapter
public class ExampleModel {
String value;
}
or
package com.example;
@AutoGsonAdapter
public interface ExampleModel {
String getValue();
}
Gson Integration
For each type adapter factory interface, register it with your Gson builder as follows:
return new GsonBuilder()
.registerTypeAdapterFactory(GsonPath.createTypeAdapterFactory(ExampleGsonTypeFactory.class))
.create();
Incremental annotation processing
You must update your build.gradle (for each module) to opt into incremental annotation processing.
When enabled, all custom annotations (annotations which are either themselves annotated with either: @AutoGsonAdapter
, @GsonSubType
, @AutoGsonAdapterFactory
) must be registered in the build.gradle (comma separated), otherwise they will be silently ignored.
Examples of this configuration are as follows:
// Standard annotation processor
javaCompileOptions {
annotationProcessorOptions {
arguments = [
'gsonpath.incremental': 'true',
'gsonpath.additionalAnnotations': 'com.example.CustomAutoGsonAdapter,com.example.CustomGsonSubType'
]
}
}
// Kotlin annotation processor (kapt)
kapt {
arguments {
arg("gsonpath.incremental", "true")
arg("gsonpath.additionalAnnotations", "com.example.CustomAutoGsonAdapter,com.example.CustomGsonSubType")
}
}
Proguard
To use proguard within your project, you must add the generated type adapter factory. Using the example above, this would be:
-keep public class com.example.ExampleGsonTypeFactoryImpl
Download
This library is available on Maven, you can add it to your project using the following gradle dependencies:
compile 'net.lachlanmckee:gsonpath:4.0.0'
apt 'net.lachlanmckee:gsonpath-compiler:4.0.0'
compile 'net.lachlanmckee:gsonpath-kt:4.0.0' // an optional Kotlin library