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 exposed for JSON 27 * serialization or deserialization. 28 * 29 * <p>This annotation has no effect unless you build {@link com.google.gson.Gson} 30 * with a {@link com.google.gson.GsonBuilder} and invoke 31 * {@link com.google.gson.GsonBuilder#excludeFieldsWithoutExposeAnnotation()} 32 * method.</p> 33 * 34 * <p>Here is an example of how this annotation is meant to be used: 35 * <pre> 36 * public class User { 37 * @Expose private String firstName; 38 * @Expose(serialize = false) private String lastName; 39 * @Expose (serialize = false, deserialize = false) private String emailAddress; 40 * private String password; 41 * } 42 * </pre> 43 * If you created Gson with {@code new Gson()}, the {@code toJson()} and {@code fromJson()} 44 * methods will use the {@code password} field along-with {@code firstName}, {@code lastName}, 45 * and {@code emailAddress} for serialization and deserialization. However, if you created Gson 46 * with {@code Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create()} 47 * then the {@code toJson()} and {@code fromJson()} methods of Gson will exclude the 48 * {@code password} field. This is because the {@code password} field is not marked with the 49 * {@code @Expose} annotation. Gson will also exclude {@code lastName} and {@code emailAddress} 50 * from serialization since {@code serialize} is set to {@code false}. Similarly, Gson will 51 * exclude {@code emailAddress} from deserialization since {@code deserialize} is set to false. 52 * 53 * <p>Note that another way to achieve the same effect would have been to just mark the 54 * {@code password} field as {@code transient}, and Gson would have excluded it even with default 55 * settings. The {@code @Expose} annotation is useful in a style of programming where you want to 56 * explicitly specify all fields that should get considered for serialization or deserialization. 57 * 58 * @author Inderjeet Singh 59 * @author Joel Leitch 60 */ 61 @Documented 62 @Retention(RetentionPolicy.RUNTIME) 63 @Target(ElementType.FIELD) 64 public @interface Expose { 65 66 /** 67 * If {@code true}, the field marked with this annotation is written out in the JSON while 68 * serializing. If {@code false}, the field marked with this annotation is skipped from the 69 * serialized output. Defaults to {@code true}. 70 * @since 1.4 71 */ serialize()72 public boolean serialize() default true; 73 74 /** 75 * If {@code true}, the field marked with this annotation is deserialized from the JSON. 76 * If {@code false}, the field marked with this annotation is skipped during deserialization. 77 * Defaults to {@code true}. 78 * @since 1.4 79 */ deserialize()80 public boolean deserialize() default true; 81 } 82