Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lachlanmckee/gsonpath
A Java annotation processor library which generates gson type adapters using basic JsonPath style annotations
https://github.com/lachlanmckee/gsonpath
adapter-factory android annotation-processor annotation-processor-library annotations gson java java-annotation-processor json jsonpath kotlin
Last synced: about 12 hours ago
JSON representation
A Java annotation processor library which generates gson type adapters using basic JsonPath style annotations
- Host: GitHub
- URL: https://github.com/lachlanmckee/gsonpath
- Owner: LachlanMcKee
- License: mit
- Created: 2016-03-11T12:50:37.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-04-17T13:27:06.000Z (over 4 years ago)
- Last Synced: 2024-10-31T14:45:43.335Z (8 days ago)
- Topics: adapter-factory, android, annotation-processor, annotation-processor-library, annotations, gson, java, java-annotation-processor, json, jsonpath, kotlin
- Language: Kotlin
- Homepage:
- Size: 1.35 MB
- Stars: 61
- Watchers: 7
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Gson Path
[](https://maven-badges.herokuapp.com/maven-central/net.lachlanmckee/gsonpath) [](https://android-arsenal.com/details/1/4191)
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](guides/interfaces.md) 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](guides/path_substitution.md) 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](https://github.com/LachlanMcKee/gsonpath-extensions-android)
## Example
Given the following JSON:
```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.
```java
@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):
```java
@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:
```java
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:
```java
package com.example;
@AutoGsonAdapter
public class ExampleModel {
String value;
}
```
or
```java
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:
```java
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:
```groovy
// 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:
```gradle
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
```