gson/com/google/gson/annotations/Since.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 the version number since a member or a type has been present.
  26  * This annotation is useful to manage versioning of your Json classes for a web-service.
  27  *
  28  * <p>
  29  * This annotation has no effect unless you build {@link com.google.gson.Gson} with a
  30  * {@link com.google.gson.GsonBuilder} and invoke
  31  * {@link com.google.gson.GsonBuilder#setVersion(double)} method.
  32  *
  33  * <p>Here is an example of how this annotation is meant to be used:</p>
  34  * <pre>
  35  * public class User {
  36  *   private String firstName;
  37  *   private String lastName;
  38  *   &#64Since(1.0) private String emailAddress;
  39  *   &#64Since(1.0) private String password;
  40  *   &#64Since(1.1) private Address address;
  41  * }
  42  * </pre>
  43  *
  44  * <p>If you created Gson with {@code new Gson()}, the {@code toJson()} and {@code fromJson()}
  45  * methods will use all the fields for serialization and deserialization. However, if you created
  46  * Gson with {@code Gson gson = new GsonBuilder().setVersion(1.0).create()} then the
  47  * {@code toJson()} and {@code fromJson()} methods of Gson will exclude the {@code address} field
  48  * since it's version number is set to {@code 1.1}.</p>
  49  *
  50  * @author Inderjeet Singh
  51  * @author Joel Leitch
  52  */
  53 @Retention(RetentionPolicy.RUNTIME)
  54 @Target({ElementType.FIELD, ElementType.TYPE})
  55 public @interface Since {
  56   /**
  57    * the value indicating a version number since this member
  58    * or type has been present.
  59    */
  60   double value();
  61 }