1 /* 2 * Copyright (C) 2008 Google Inc. 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17 package com.google.gson.annotations; 18 19 import java.lang.annotation.Documented; 20 import java.lang.annotation.ElementType; 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 import java.lang.annotation.Target; 24 25 /** 26 * An annotation that indicates this member should be serialized to JSON with 27 * the provided name value as its field name. 28 * 29 * <p>This annotation will override any {@link com.google.gson.FieldNamingPolicy}, including 30 * the default field naming policy, that may have been set on the {@link com.google.gson.Gson} 31 * instance. A different naming policy can set using the {@code GsonBuilder} class. See 32 * {@link com.google.gson.GsonBuilder#setFieldNamingPolicy(com.google.gson.FieldNamingPolicy)} 33 * for more information.</p> 34 * 35 * <p>Here is an example of how this annotation is meant to be used:</p> 36 * <pre> 37 * public class MyClass { 38 * @SerializedName("name") String a; 39 * @SerializedName(value="name1", alternate={"name2", "name3"}) String b; 40 * String c; 41 * 42 * public MyClass(String a, String b, String c) { 43 * this.a = a; 44 * this.b = b; 45 * this.c = c; 46 * } 47 * } 48 * </pre> 49 * 50 * <p>The following shows the output that is generated when serializing an instance of the 51 * above example class:</p> 52 * <pre> 53 * MyClass target = new MyClass("v1", "v2", "v3"); 54 * Gson gson = new Gson(); 55 * String json = gson.toJson(target); 56 * System.out.println(json); 57 * 58 * ===== OUTPUT ===== 59 * {"name":"v1","name1":"v2","c":"v3"} 60 * </pre> 61 * 62 * <p>NOTE: The value you specify in this annotation must be a valid JSON field name.</p> 63 * While deserializing, all values specified in the annotation will be deserialized into the field. 64 * For example: 65 * <pre> 66 * MyClass target = gson.fromJson("{'name1':'v1'}", MyClass.class); 67 * assertEquals("v1", target.b); 68 * target = gson.fromJson("{'name2':'v2'}", MyClass.class); 69 * assertEquals("v2", target.b); 70 * target = gson.fromJson("{'name3':'v3'}", MyClass.class); 71 * assertEquals("v3", target.b); 72 * </pre> 73 * Note that MyClass.b is now deserialized from either name1, name2 or name3. 74 * 75 * @see com.google.gson.FieldNamingPolicy 76 * 77 * @author Inderjeet Singh 78 * @author Joel Leitch 79 */ 80 @Documented 81 @Retention(RetentionPolicy.RUNTIME) 82 @Target({ElementType.FIELD, ElementType.METHOD}) 83 public @interface SerializedName { 84 85 /** 86 * @return the desired name of the field when it is serialized or deserialized 87 */ value()88 String value(); 89 /** 90 * @return the alternative names of the field when it is deserialized 91 */ alternate()92 String[] alternate() default {}; 93 } 94