2 * Copyright (C) 2008 Google Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 package com
.google
.gson
;
19 import java
.lang
.reflect
.Type
;
22 * Interface representing a custom serializer for Json. You should write a custom serializer, if
23 * you are not happy with the default serialization done by Gson. You will also need to register
24 * this serializer through {@link com.google.gson.GsonBuilder#registerTypeAdapter(Type, Object)}.
26 * <p>Let us look at example where defining a serializer will be useful. The {@code Id} class
27 * defined below has two fields: {@code clazz} and {@code value}.</p>
30 * public class Id<T> {
31 * private final Class<T> clazz;
32 * private final long value;
34 * public Id(Class<T> clazz, long value) {
39 * public long getValue() {
45 * <p>The default serialization of {@code Id(com.foo.MyObject.class, 20L)} will be
46 * <code>{"clazz":com.foo.MyObject,"value":20}</code>. Suppose, you just want the output to be
47 * the value instead, which is {@code 20} in this case. You can achieve that by writing a custom
51 * class IdSerializer implements JsonSerializer<Id>() {
52 * public JsonElement serialize(Id id, Type typeOfId, JsonSerializationContext context) {
53 * return new JsonPrimitive(id.getValue());
58 * <p>You will also need to register {@code IdSerializer} with Gson as follows:</p>
60 * Gson gson = new GsonBuilder().registerTypeAdapter(Id.class, new IdSerializer()).create();
63 * <p>New applications should prefer {@link TypeAdapter}, whose streaming API
64 * is more efficient than this interface's tree API.
66 * @author Inderjeet Singh
69 * @param <T> type for which the serializer is being registered. It is possible that a serializer
70 * may be asked to serialize a specific generic type of the T.
72 public interface JsonSerializer
<T
> {
75 * Gson invokes this call-back method during serialization when it encounters a field of the
78 * <p>In the implementation of this call-back method, you should consider invoking
79 * {@link JsonSerializationContext#serialize(Object, Type)} method to create JsonElements for any
80 * non-trivial field of the {@code src} object. However, you should never invoke it on the
81 * {@code src} object itself since that will cause an infinite loop (Gson will call your
82 * call-back method again).</p>
84 * @param src the object that needs to be converted to Json.
85 * @param typeOfSrc the actual type (fully genericized version) of the source object.
86 * @return a JsonElement corresponding to the specified object.
88 public JsonElement
serialize(T src
, Type typeOfSrc
, JsonSerializationContext context
);