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