Moshi Lazy Adapters
A collection of simple JsonAdapters for Moshi.
This library acts as an extension to Moshi by providing general purpose, yet useful JsonAdapter
s that are not present in the main library. Most provided adapters are linked via specialized JsonQualifier
annotations that alter serialization/deserialization strategies.
How To Use It
This library is not forcing any of it's own adapters by default. To leverage from any of the provided annotations/adapters add their respective factory to your Moshi.Builder
:
// Creates a Moshi instance with an adapter that will handle the @Wrapped annotations.
Moshi moshi = new Moshi.Builder()
.add(Wrapped.ADAPTER_FACTORY)
.build();
Overall contract
Every declared annotation/adapter in this library (unless specified in the class's documentation) supports adapter composition. Which means that no JsonAdapter.Factory
will short circuit adapter construction on it's own annotation, and instead will delegate to the next adapter returned by Moshi
. Meaning that given the following type declaration:
interface WebService {
@GET("/data")
@Wrapped(path={"result", "data"}) @FirstElement MyData getData();
}
The resulting JsonAdapter
will unwrap a list of MyData
from the json response and return only the first element of that list.
One important concept to keep in mind, that the order of declared annotations in the example above does not have any influence on the way how the final adapter will be constructed. Instead the order of the JsonAdapter.Factory
's added to the Moshi
instance is what plays a major role in overall behavior. Meaning that in order for the example above to satisfy the expected result, one must add the factories in the following order:
Moshi moshi = new Moshi.Builder()
.add(Wrapped.ADAPTER_FACTORY)
.add(FirstElement.ADAPTER_FACTORY)
.build()
Some Lazy Adapters
@Wrapped
Some apis enjoy wrapping the response object inside other json objects. This creates a lot of inconvenience when it comes to consuming the request. The following example contains a list of a users favorite pokemon which is wrapped behind two keys:
{
"favorite_pokemon": {
"pokemons": [
"Snorlax",
"Pikachu",
"Bulbasaur",
"Charmander",
"Squirtle"
]
}
}
In the end the consumer is just interested in the names of the pokemon, but the json object forces to create a wrapping object, which will contain the list:
class FavoritePokemonResponse {
FavoritePokemon favorite_pokemon;
}
class FavoritePokemon {
List<String> pokemons;
}
A custom adapter would be another option, and WrappedJsonAdapter
is just the one. By annotating the response type with @Wrapped
and providing the path to the desired list, the need for an additional object is dropped:
// This assumes that Retrofit is used to obtain the response.
interface PokemonService {
@GET("/pokemon/favorite")
@Wrapped({"favorite_pokemon", "pokemons"}) Call<List<String>> getFavorite();
}
No need for a new class, which results in less code and less methods generated by the consumer code. You can also annotate any field in your response entity and the same rules will apply.
@FallbackOnNull
Primitives are simple and safe. Primitives have also a smaller memory footprint. Some apis may return null
for values that are normally processed as primitives. A safe alternative would be to use their boxed counterparts, but that would result in redundant boxing and unboxing. By annotating any primitive field with @FallbackOnNull
the consumer can specify a default value for the field, in case it's json representation is null.
[
{
"name": "Pikachu",
"number_of_wins": 1
},
{
"name": "Magikarp",
"number_of_wins": null
}
]
The json above contains a list of pokemon of a user with their names and the number of wins the respective pokemon has obtained during it's trainings of fights. Notice that the 'Magikarp' pokemon has null
wins. Normally the representing POJO would declare the filed as Integer
, but #perfmatters. With @FallbackOnNull
the Pokemon
object can be declared as:
class Pokemon {
String name;
@FallbackOnNull int number_of_wins;
}
If the incoming value would be null
the number_of_wins
field would default to Integer.MIN_VALUE
, this can be altered by providing an alternative fallback:
@FallbackOnNull(fallbackInt = -1) int number_of_wins;
See FallbackOnNull's documentation for a full reference.
List of provided Adapters
- DefaultOnDataMismatchAdapter - Allows the consumer to provided a default fallback value for any type.
- SerializeNulls (annotation) - Serializes a value even if it's
null
; - FirstElement (annotation) - Deserializes only the first element of a list.
- LastElement (annotation) - Deserializes only the last element of a list.
- ElementAt (annotation) - Deserializes an element from a specified position of a list.
- FallbackOnNull (annotation) - Fallbacks to a default value in case the json field is
null
. - FallbackEnum (annotation) - Fallbacks to a default enum value if the parsed value can not be matched to an existing one.
- Wrapped (annotation) - Unwraps a json object under the specified path when parsing, and wraps it when serializing to json.
- SerializeOnly (annotation) - Only serializes the annotated field, and ignores it during deserialization.
- DeserializeOnly (annotation) - Only deserializes the annotated field, and ignores it during serialization.
- Transient (annotation) - (Targets methods only) indicates that a field should be ignored for serialization/deserialization.
- SerializeOnlyNonEmpty (annotation) - Will serialize a collection or array only if it contains at-least one value.
Download
Download the latest JAR or depend via Maven:
<dependency>
<groupId>com.serjltt.moshi</groupId>
<artifactId>moshi-lazy-adapters</artifactId>
<version>x.y</version>
</dependency>
or Gradle:
compile 'com.serjltt.moshi:moshi-lazy-adapters:x.y'
Snapshots of the development version are available in Sonatype's snapshots
repository.
License
Copyright 2017 Serj Lotutovici
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.