github.com/keysonZZZ/kmg@v0.0.0-20151121023212-05317bfd7d39/kmgRpc/kmgRpcJava/java/src/com/google/gson/ExclusionStrategy.java (about)

     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;
    18  
    19  /**
    20   * A strategy (or policy) definition that is used to decide whether or not a field or top-level
    21   * class should be serialized or deserialized as part of the JSON output/input. For serialization,
    22   * if the {@link #shouldSkipClass(Class)} method returns true then that class or field type
    23   * will not be part of the JSON output.  For deserialization, if {@link #shouldSkipClass(Class)}
    24   * returns true, then it will not be set as part of the Java object structure.
    25   *
    26   * <p>The following are a few examples that shows how you can use this exclusion mechanism.
    27   *
    28   * <p><strong>Exclude fields and objects based on a particular class type:</strong>
    29   * <pre class="code">
    30   * private static class SpecificClassExclusionStrategy implements ExclusionStrategy {
    31   *   private final Class&lt;?&gt; excludedThisClass;
    32   *
    33   *   public SpecificClassExclusionStrategy(Class&lt;?&gt; excludedThisClass) {
    34   *     this.excludedThisClass = excludedThisClass;
    35   *   }
    36   *
    37   *   public boolean shouldSkipClass(Class&lt;?&gt; clazz) {
    38   *     return excludedThisClass.equals(clazz);
    39   *   }
    40   *
    41   *   public boolean shouldSkipField(FieldAttributes f) {
    42   *     return excludedThisClass.equals(f.getDeclaredClass());
    43   *   }
    44   * }
    45   * </pre>
    46   *
    47   * <p><strong>Excludes fields and objects based on a particular annotation:</strong>
    48   * <pre class="code">
    49   * public &#64interface FooAnnotation {
    50   *   // some implementation here
    51   * }
    52   *
    53   * // Excludes any field (or class) that is tagged with an "&#64FooAnnotation"
    54   * private static class FooAnnotationExclusionStrategy implements ExclusionStrategy {
    55   *   public boolean shouldSkipClass(Class&lt;?&gt; clazz) {
    56   *     return clazz.getAnnotation(FooAnnotation.class) != null;
    57   *   }
    58   *
    59   *   public boolean shouldSkipField(FieldAttributes f) {
    60   *     return f.getAnnotation(FooAnnotation.class) != null;
    61   *   }
    62   * }
    63   * </pre>
    64   *
    65   * <p>Now if you want to configure {@code Gson} to use a user defined exclusion strategy, then
    66   * the {@code GsonBuilder} is required. The following is an example of how you can use the
    67   * {@code GsonBuilder} to configure Gson to use one of the above sample:
    68   * <pre class="code">
    69   * ExclusionStrategy excludeStrings = new UserDefinedExclusionStrategy(String.class);
    70   * Gson gson = new GsonBuilder()
    71   *     .setExclusionStrategies(excludeStrings)
    72   *     .create();
    73   * </pre>
    74   *
    75   * <p>For certain model classes, you may only want to serialize a field, but exclude it for
    76   * deserialization. To do that, you can write an {@code ExclusionStrategy} as per normal;
    77   * however, you would register it with the
    78   * {@link GsonBuilder#addDeserializationExclusionStrategy(ExclusionStrategy)} method.
    79   * For example:
    80   * <pre class="code">
    81   * ExclusionStrategy excludeStrings = new UserDefinedExclusionStrategy(String.class);
    82   * Gson gson = new GsonBuilder()
    83   *     .addDeserializationExclusionStrategy(excludeStrings)
    84   *     .create();
    85   * </pre>
    86   *
    87   * @author Inderjeet Singh
    88   * @author Joel Leitch
    89   *
    90   * @see GsonBuilder#setExclusionStrategies(ExclusionStrategy...)
    91   * @see GsonBuilder#addDeserializationExclusionStrategy(ExclusionStrategy)
    92   * @see GsonBuilder#addSerializationExclusionStrategy(ExclusionStrategy)
    93   *
    94   * @since 1.4
    95   */
    96  public interface ExclusionStrategy {
    97  
    98    /**
    99     * @param f the field object that is under test
   100     * @return true if the field should be ignored; otherwise false
   101     */
   102    public boolean shouldSkipField(FieldAttributes f);
   103  
   104    /**
   105     * @param clazz the class object that is under test
   106     * @return true if the class should be ignored; otherwise false
   107     */
   108    public boolean shouldSkipClass(Class<?> clazz);
   109  }