gson/com/google/gson/annotations/Expose.java

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