2011-07-11 18:46:52 +02:00
|
|
|
/*
|
|
|
|
* Copyright (C) 2011 Google Inc.
|
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
|
2011-11-20 16:23:08 +01:00
|
|
|
package com.google.gson;
|
2011-07-11 18:46:52 +02:00
|
|
|
|
2011-08-19 04:35:29 +02:00
|
|
|
import java.io.IOException;
|
|
|
|
import java.io.Reader;
|
|
|
|
import java.io.StringReader;
|
|
|
|
import java.io.StringWriter;
|
|
|
|
import java.io.Writer;
|
|
|
|
|
2011-12-05 20:50:49 +01:00
|
|
|
import com.google.gson.internal.bind.JsonElementWriter;
|
|
|
|
import com.google.gson.internal.bind.JsonTreeReader;
|
|
|
|
import com.google.gson.reflect.TypeToken;
|
|
|
|
import com.google.gson.stream.JsonReader;
|
|
|
|
import com.google.gson.stream.JsonToken;
|
|
|
|
import com.google.gson.stream.JsonWriter;
|
|
|
|
|
2011-12-03 00:11:28 +01:00
|
|
|
/**
|
2011-12-03 20:46:25 +01:00
|
|
|
* Converts between Java objects and JSON. Applications use type adapters both
|
|
|
|
* for customizing types' JSON forms, and for JSON conversions.
|
|
|
|
*
|
|
|
|
* <h3>Defining a type's JSON form</h3>
|
|
|
|
* By default Gson converts application classes to JSON using its built-in type
|
|
|
|
* adapters. Change your Java objects' JSON representation by subclassing {@code
|
|
|
|
* TypeAdapter} and registering the subclass with a {@code GsonBuilder}. Here's
|
|
|
|
* an example of a type adapter for an (X,Y) coordinate point: <pre> {@code
|
|
|
|
*
|
|
|
|
* public class PointAdapter extends TypeAdapter<Point> {
|
|
|
|
* public Point read(JsonReader reader) throws IOException {
|
|
|
|
* if (reader.peek() == JsonToken.NULL) {
|
|
|
|
* reader.nextNull();
|
|
|
|
* return null;
|
|
|
|
* }
|
|
|
|
* String xy = reader.nextString();
|
|
|
|
* String[] parts = xy.split(",");
|
|
|
|
* int x = Integer.parseInt(parts[0]);
|
|
|
|
* int y = Integer.parseInt(parts[1]);
|
|
|
|
* return new Point(x, y);
|
|
|
|
* }
|
|
|
|
* public void write(JsonWriter writer, Point value) throws IOException {
|
|
|
|
* if (value == null) {
|
|
|
|
* writer.nullValue();
|
|
|
|
* return;
|
|
|
|
* }
|
|
|
|
* String xy = value.getX() + "," + value.getY();
|
|
|
|
* writer.value(xy);
|
|
|
|
* }
|
|
|
|
* }}</pre>
|
|
|
|
* With this type adapter installed, Gson will convert {@code Points} to JSON as
|
|
|
|
* strings like {@code "5,8"} rather than objects like {@code {"x":5,"y":8}}. In
|
|
|
|
* this case the type adapter binds a rich Java class to a compact JSON value.
|
|
|
|
*
|
|
|
|
* <p>The {@link #read(JsonReader) read()} method must read exactly one value
|
|
|
|
* and {@link #write(JsonWriter,Object) write()} must write exactly one value.
|
|
|
|
* For primitive types this is means readers should make exactly one call to
|
|
|
|
* <code>next<i>Type</i>()</code> and writers should make exactly one call to
|
|
|
|
* one of <code>value()</code> or <code>nullValue()</code>. For composite types,
|
|
|
|
* type adapters should start with a call to <code>begin<i>Type</i>()</code>,
|
|
|
|
* convert the entire contents of the object or array, and finish with a call
|
|
|
|
* to <code>end<i>Type</i>()</code>. Failing to convert a value or converting
|
|
|
|
* too many values will disrupt the cadence of the caller and may cause the
|
|
|
|
* application to crash.
|
|
|
|
*
|
|
|
|
* <p>Type adapters should be prepared to read null from the stream and write it
|
|
|
|
* to the stream. If your {@code Gson} instance has been configured to {@link
|
|
|
|
* GsonBuilder#serializeNulls()}, these will be written to the final document.
|
|
|
|
* Otherwise the value (and the corresponding name when writing to a JSON
|
|
|
|
* object) will be omitted automatically. In either case your type adapter must
|
|
|
|
* handle null.
|
|
|
|
*
|
|
|
|
* <p>To use a custom type adapter with Gson, you must <i>register</i> it with a
|
|
|
|
* {@link GsonBuilder}: <pre> {@code
|
|
|
|
*
|
|
|
|
* GsonBuilder builder = new GsonBuilder();
|
|
|
|
* builder.registerTypeAdapter(Point.class, new PointAdapter());
|
|
|
|
* ...
|
|
|
|
* Gson gson = builder.create();
|
|
|
|
* }</pre>
|
|
|
|
*
|
|
|
|
* <h3>JSON Conversion</h3>
|
|
|
|
* <p>Retrieve a type adapter from a {@code Gson} instance to deserialize a JSON
|
|
|
|
* document into a Java object: <pre> {@code
|
|
|
|
*
|
|
|
|
* String json = "{'origin':'0,0','points':['1,2','3,4']}";
|
|
|
|
* TypeAdapter<Graph> graphAdapter = gson.getAdapter(Graph.class);
|
|
|
|
* Graph graph = graphAdapter.fromJson(json);
|
|
|
|
* }</pre>
|
|
|
|
* ...or serialize a Java object to a JSON document: <pre> {@code
|
|
|
|
*
|
|
|
|
* Graph graph = new Graph(...);
|
|
|
|
* TypeAdapter<Graph> graphAdapter = gson.getAdapter(Graph.class);
|
|
|
|
* String json = graphAdapter.toJson(graph);
|
|
|
|
* }</pre>
|
|
|
|
*
|
|
|
|
* <p>Type adapters are <strong>type-specific</strong>. For example, a {@code
|
|
|
|
* TypeAdapter<Date>} can convert {@code Date} instances to JSON and JSON to
|
|
|
|
* instances of {@code Date}, but cannot convert any other types.
|
2011-12-03 00:11:28 +01:00
|
|
|
*
|
|
|
|
* @since 2.1
|
|
|
|
*/
|
2011-07-11 18:46:52 +02:00
|
|
|
public abstract class TypeAdapter<T> {
|
|
|
|
|
2011-12-03 20:46:25 +01:00
|
|
|
/**
|
|
|
|
* Writes one JSON value (an array, object, string, number, boolean or null)
|
|
|
|
* for {@code value}.
|
|
|
|
*
|
|
|
|
* @param value the Java object to write. May be null.
|
|
|
|
*/
|
|
|
|
public abstract void write(JsonWriter out, T value) throws IOException;
|
2011-07-11 18:46:52 +02:00
|
|
|
|
2011-12-03 20:46:25 +01:00
|
|
|
/**
|
|
|
|
* Converts {@code value} to a JSON document and writes it to {@code out}.
|
|
|
|
* Unlike Gson's similar {@link Gson#toJson(JsonElement, Appendable) toJson}
|
|
|
|
* method, this write is strict. Create a {@link
|
|
|
|
* JsonWriter#setLenient(boolean) lenient} {@code JsonWriter} and call
|
|
|
|
* {@link #write(com.google.gson.stream.JsonWriter, Object)} for lenient
|
|
|
|
* writing.
|
|
|
|
*
|
|
|
|
* @param value the Java object to convert. May be null.
|
|
|
|
*/
|
2011-12-02 23:57:30 +01:00
|
|
|
public final void toJson(Writer out, T value) throws IOException {
|
2011-07-11 18:46:52 +02:00
|
|
|
JsonWriter writer = new JsonWriter(out);
|
|
|
|
write(writer, value);
|
|
|
|
}
|
|
|
|
|
2011-12-05 20:50:49 +01:00
|
|
|
/**
|
|
|
|
* This wrapper method is used to make a type adapter null tolerant. In general, a
|
|
|
|
* type adapter is required to handle nulls in write and read methods. Here is how this
|
|
|
|
* is typically done:<br>
|
|
|
|
* <pre>{@code
|
|
|
|
Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class,
|
|
|
|
new TypeAdapter<Foo>() {
|
|
|
|
public Foo read(JsonReader in) throws IOException {
|
|
|
|
if (in.peek() == JsonToken.NULL) {
|
|
|
|
in.nextNull();
|
|
|
|
return null;
|
|
|
|
}
|
|
|
|
// read a Foo from in and return it
|
|
|
|
}
|
|
|
|
public void write(JsonWriter out, Foo src) throws IOException {
|
|
|
|
if (src == null) {
|
|
|
|
out.nullValue();
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
// write src as JSON to out
|
|
|
|
}
|
|
|
|
).create();
|
|
|
|
* }</pre>
|
|
|
|
* You can avoid this boilerplate handling of nulls by wrapping your type adapter with
|
|
|
|
* {@link #nullSafe(TypeAdapter)} method. Here is how we will rewrite the above example:
|
|
|
|
* <pre>{@code
|
|
|
|
Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class,
|
|
|
|
TypeAdapter.nullSafe(new TypeAdapter<Foo>() {
|
|
|
|
public Foo read(JsonReader in) throws IOException {
|
|
|
|
// read a Foo from in and return it
|
|
|
|
}
|
|
|
|
public void write(JsonWriter out, Foo src) throws IOException {
|
|
|
|
// write src as JSON to out
|
|
|
|
}
|
|
|
|
)).create();
|
|
|
|
* }</pre>
|
|
|
|
* Note that we didn't need to check for nulls in our type adapter after we used nullSafe.
|
|
|
|
*/
|
|
|
|
public static <T> TypeAdapter<T> nullSafe(final TypeAdapter<T> typeAdapter) {
|
|
|
|
return new TypeAdapter<T>() {
|
|
|
|
@Override public void write(JsonWriter out, T value) throws IOException {
|
|
|
|
if (value == null) {
|
|
|
|
out.nullValue();
|
|
|
|
} else {
|
|
|
|
typeAdapter.write(out, value);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
@Override public T read(JsonReader reader) throws IOException {
|
|
|
|
if (reader.peek() == JsonToken.NULL) {
|
|
|
|
reader.nextNull();
|
|
|
|
return null;
|
|
|
|
}
|
|
|
|
return typeAdapter.read(reader);
|
|
|
|
}
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
2011-12-03 20:46:25 +01:00
|
|
|
/**
|
|
|
|
* Converts {@code value} to a JSON document. Unlike Gson's similar {@link
|
|
|
|
* Gson#toJson(Object) toJson} method, this write is strict. Create a {@link
|
|
|
|
* JsonWriter#setLenient(boolean) lenient} {@code JsonWriter} and call
|
|
|
|
* {@link #write(com.google.gson.stream.JsonWriter, Object)} for lenient
|
|
|
|
* writing.
|
|
|
|
*
|
|
|
|
* @param value the Java object to convert. May be null.
|
|
|
|
*/
|
|
|
|
public final String toJson(T value) throws IOException {
|
|
|
|
StringWriter stringWriter = new StringWriter();
|
|
|
|
toJson(stringWriter, value);
|
|
|
|
return stringWriter.toString();
|
2011-07-11 18:46:52 +02:00
|
|
|
}
|
|
|
|
|
2011-12-03 20:46:25 +01:00
|
|
|
/**
|
|
|
|
* Converts {@code value} to a JSON tree.
|
|
|
|
*
|
|
|
|
* @param value the Java object to convert. May be null.
|
|
|
|
* @return the converted JSON tree. May be {@link JsonNull}.
|
|
|
|
*/
|
|
|
|
public JsonElement toJsonTree(T value) {
|
2011-08-03 04:40:18 +02:00
|
|
|
try {
|
2011-09-30 08:32:33 +02:00
|
|
|
JsonElementWriter jsonWriter = new JsonElementWriter();
|
2011-08-03 04:40:18 +02:00
|
|
|
jsonWriter.setLenient(true);
|
2011-12-03 20:46:25 +01:00
|
|
|
write(jsonWriter, value);
|
2011-09-30 08:32:33 +02:00
|
|
|
return jsonWriter.get();
|
2011-08-03 04:40:18 +02:00
|
|
|
} catch (IOException e) {
|
2011-08-19 04:35:29 +02:00
|
|
|
throw new JsonIOException(e);
|
2011-08-03 04:40:18 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2011-12-03 20:46:25 +01:00
|
|
|
/**
|
|
|
|
* Reads one JSON value (an array, object, string, number, boolean or null)
|
|
|
|
* and converts it to a Java object. Returns the converted object.
|
|
|
|
*
|
|
|
|
* @return the converted Java object. May be null.
|
|
|
|
*/
|
|
|
|
public abstract T read(JsonReader in) throws IOException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Converts the JSON document in {@code in} to a Java object. Unlike Gson's
|
|
|
|
* similar {@link Gson#fromJson(java.io.Reader, Class) fromJson} method, this
|
|
|
|
* read is strict. Create a {@link JsonReader#setLenient(boolean) lenient}
|
|
|
|
* {@code JsonReader} and call {@link #read(JsonReader)} for lenient reading.
|
|
|
|
*
|
|
|
|
* @return the converted Java object. May be null.
|
|
|
|
*/
|
|
|
|
public final T fromJson(Reader in) throws IOException {
|
|
|
|
JsonReader reader = new JsonReader(in);
|
|
|
|
reader.setLenient(true); // TODO: non-lenient?
|
|
|
|
return read(reader);
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Converts the JSON document in {@code json} to a Java object. Unlike Gson's
|
|
|
|
* similar {@link Gson#fromJson(String, Class) fromJson} method, this read is
|
|
|
|
* strict. Create a {@link JsonReader#setLenient(boolean) lenient} {@code
|
|
|
|
* JsonReader} and call {@link #read(JsonReader)} for lenient reading.
|
|
|
|
*
|
|
|
|
* @return the converted Java object. May be null.
|
|
|
|
*/
|
|
|
|
public final T fromJson(String json) throws IOException {
|
|
|
|
return fromJson(new StringReader(json));
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Converts {@code jsonTree} to a Java object.
|
|
|
|
*
|
|
|
|
* @param jsonTree the Java object to convert. May be {@link JsonNull}.
|
|
|
|
*/
|
|
|
|
public T fromJsonTree(JsonElement jsonTree) {
|
2011-08-03 04:40:18 +02:00
|
|
|
try {
|
2011-12-03 20:46:25 +01:00
|
|
|
JsonReader jsonReader = new JsonTreeReader(jsonTree);
|
2011-08-03 04:40:18 +02:00
|
|
|
jsonReader.setLenient(true);
|
|
|
|
return read(jsonReader);
|
|
|
|
} catch (IOException e) {
|
2011-08-19 04:35:29 +02:00
|
|
|
throw new JsonIOException(e);
|
2011-08-03 04:40:18 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2011-12-03 00:11:28 +01:00
|
|
|
/**
|
2011-12-03 20:46:25 +01:00
|
|
|
* Creates type adapters for set of related types. Type adapter factories are
|
|
|
|
* most useful when several types share similar structure in their JSON form.
|
|
|
|
*
|
|
|
|
* <h3>Example: Converting enums to lowercase</h3>
|
|
|
|
* In this example, we implement a factory that creates type adapters for all
|
|
|
|
* enums. The type adapters will write enums in lowercase, despite the fact
|
|
|
|
* that they're defined in {@code CONSTANT_CASE} in the corresponding Java
|
|
|
|
* model: <pre> {@code
|
|
|
|
*
|
|
|
|
* public class LowercaseEnumTypeAdapterFactory implements TypeAdapter.Factory {
|
|
|
|
* public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type) {
|
|
|
|
* Class<T> rawType = (Class<T>) type.getRawType();
|
|
|
|
* if (!rawType.isEnum()) {
|
|
|
|
* return null;
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* final Map<String, T> lowercaseToConstant = new HashMap<String, T>();
|
|
|
|
* for (T constant : rawType.getEnumConstants()) {
|
|
|
|
* lowercaseToConstant.put(toLowercase(constant), constant);
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* return new TypeAdapter<T>() {
|
|
|
|
* public void write(JsonWriter out, T value) throws IOException {
|
|
|
|
* if (value == null) {
|
|
|
|
* out.nullValue();
|
|
|
|
* } else {
|
|
|
|
* out.value(toLowercase(value));
|
|
|
|
* }
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* public T read(JsonReader reader) throws IOException {
|
|
|
|
* if (reader.peek() == JsonToken.NULL) {
|
|
|
|
* reader.nextNull();
|
|
|
|
* return null;
|
|
|
|
* } else {
|
|
|
|
* return lowercaseToConstant.get(reader.nextString());
|
|
|
|
* }
|
|
|
|
* }
|
|
|
|
* };
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* private String toLowercase(Object o) {
|
|
|
|
* return o.toString().toLowerCase(Locale.US);
|
|
|
|
* }
|
|
|
|
* }
|
|
|
|
* }</pre>
|
|
|
|
*
|
|
|
|
* <p>Type adapter factories select which types they provide type adapters
|
|
|
|
* for. If a factory cannot support a given type, it must return null when
|
|
|
|
* that type is passed to {@link #create}. Factories should expect {@code
|
|
|
|
* create()} to be called on them for many types and should return null for
|
|
|
|
* most of those types. In the above example the factory returns null for
|
|
|
|
* calls to {@code create()} where {@code type} is not an enum.
|
|
|
|
*
|
|
|
|
* <p>A factory is typically called once per type, but the returned type
|
|
|
|
* adapter may be used many times. It is most efficient to do expensive work
|
|
|
|
* like reflection in {@code create()} so that the type adapter's {@code
|
|
|
|
* read()} and {@code write()} methods can be very fast. In this example the
|
|
|
|
* mapping from lowercase name to enum value is computed eagerly.
|
|
|
|
*
|
|
|
|
* <p>As with type adapters, factories must be <i>registered</i> with a {@link
|
|
|
|
* GsonBuilder} for them to take effect: <pre> {@code
|
|
|
|
*
|
|
|
|
* GsonBuilder builder = new GsonBuilder();
|
|
|
|
* builder.registerTypeAdapterFactory(new LowercaseEnumTypeAdapterFactory());
|
|
|
|
* ...
|
|
|
|
* Gson gson = builder.create();
|
|
|
|
* }</pre>
|
|
|
|
* If multiple factories support the same type, the factory registered earlier
|
|
|
|
* takes precedence.
|
|
|
|
*
|
|
|
|
* <h3>Example: composing other type adapters</h3>
|
|
|
|
* In this example we implement a factory for Guava's {@code Multiset}
|
|
|
|
* collection type. The factory can be used to create type adapters for
|
|
|
|
* multisets of any element type: the type adapter for {@code
|
|
|
|
* Multiset<String>} is different from the type adapter for {@code
|
|
|
|
* Multiset<URL>}.
|
|
|
|
*
|
|
|
|
* <p>The type adapter <i>delegates</i> to another type adapter for the
|
|
|
|
* multiset elements. It figures out the element type by reflecting on the
|
|
|
|
* multiset's type token. A {@code Gson} is passed in to {@code create} for
|
|
|
|
* just this purpose: <pre> {@code
|
|
|
|
*
|
|
|
|
* public class MultisetTypeAdapterFactory implements TypeAdapter.Factory {
|
|
|
|
* public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> typeToken) {
|
|
|
|
* Type type = typeToken.getType();
|
|
|
|
* if (typeToken.getRawType() != Multiset.class
|
|
|
|
* || !(type instanceof ParameterizedType)) {
|
|
|
|
* return null;
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* Type elementType = ((ParameterizedType) type).getActualTypeArguments()[0];
|
|
|
|
* TypeAdapter<?> elementAdapter = gson.getAdapter(TypeToken.get(elementType));
|
|
|
|
* return (TypeAdapter<T>) newMultisetAdapter(elementAdapter);
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* private <E> TypeAdapter<Multiset<E>> newMultisetAdapter(
|
|
|
|
* final TypeAdapter<E> elementAdapter) {
|
|
|
|
* return new TypeAdapter<Multiset<E>>() {
|
|
|
|
* public void write(JsonWriter out, Multiset<E> value) throws IOException {
|
|
|
|
* if (value == null) {
|
|
|
|
* out.nullValue();
|
|
|
|
* return;
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* out.beginArray();
|
|
|
|
* for (Multiset.Entry<E> entry : value.entrySet()) {
|
|
|
|
* out.value(entry.getCount());
|
|
|
|
* elementAdapter.write(out, entry.getElement());
|
|
|
|
* }
|
|
|
|
* out.endArray();
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* public Multiset<E> read(JsonReader in) throws IOException {
|
|
|
|
* if (in.peek() == JsonToken.NULL) {
|
|
|
|
* in.nextNull();
|
|
|
|
* return null;
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* Multiset<E> result = LinkedHashMultiset.create();
|
|
|
|
* in.beginArray();
|
|
|
|
* while (in.hasNext()) {
|
|
|
|
* int count = in.nextInt();
|
|
|
|
* E element = elementAdapter.read(in);
|
|
|
|
* result.add(element, count);
|
|
|
|
* }
|
|
|
|
* in.endArray();
|
|
|
|
* return result;
|
|
|
|
* }
|
|
|
|
* };
|
|
|
|
* }
|
|
|
|
* }
|
|
|
|
* }</pre>
|
|
|
|
* Delegating from one type adapter to another is extremely powerful; it's
|
|
|
|
* the foundation of how Gson converts Java objects and collections. Whenever
|
|
|
|
* possible your factory should retrieve its delegate type adapter in the
|
|
|
|
* {@code create()} method; this ensures potentially-expensive type adapter
|
|
|
|
* creation happens only once.
|
|
|
|
*
|
2011-12-03 00:11:28 +01:00
|
|
|
* @since 2.1
|
|
|
|
*/
|
2011-08-03 02:17:17 +02:00
|
|
|
public interface Factory {
|
2011-12-03 20:46:25 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns a type adapter for {@code type}, or null if this factory doesn't
|
|
|
|
* support {@code type}.
|
|
|
|
*/
|
2011-11-25 06:40:17 +01:00
|
|
|
<T> TypeAdapter<T> create(Gson gson, TypeToken<T> type);
|
2011-07-11 18:46:52 +02:00
|
|
|
}
|
|
|
|
}
|