1 package com.fasterxml.jackson.databind.jsontype; 2 3 import java.util.Collection; 4 5 import com.fasterxml.jackson.annotation.JsonTypeInfo; 6 import com.fasterxml.jackson.annotation.JsonTypeInfo.As; 7 import com.fasterxml.jackson.databind.DeserializationConfig; 8 import com.fasterxml.jackson.databind.JavaType; 9 import com.fasterxml.jackson.databind.SerializationConfig; 10 11 /** 12 * Interface that defines builders that are configured based on 13 * annotations (like {@link com.fasterxml.jackson.annotation.JsonTypeInfo} or JAXB annotations), 14 * and produce type serializers and deserializers used for 15 * handling type information embedded in JSON to allow for safe 16 * polymorphic type handling. 17 *<p> 18 * Builder is first initialized by calling {@link #init} method, and then 19 * configured using 'set' methods like {@link #inclusion}. 20 * Finally, after calling all configuration methods, 21 * {@link #buildTypeSerializer} or {@link #buildTypeDeserializer} 22 * will be called to get actual type resolver constructed 23 * and used for resolving types for configured base type and its 24 * subtypes. 25 *<p> 26 * Note that instances are used for two related but distinct use cases: 27 *<ul> 28 * <li>To create builders to use with explicit type information 29 * inclusion (usually via <code>@JsonTypeInfo</code> annotation) 30 * </li> 31 * <li>To create builders when "default typing" is used; if so, type information 32 * is automatically included for certain kind of types, regardless of annotations 33 * </li> 34 *</ul> 35 * Important distinction between the cases is that in first case, calls to 36 * create builders are only made when builders are certainly needed; whereas 37 * in second case builder has to first verify whether type information is 38 * applicable for given type, and if not, just return null to indicate this. 39 */ 40 public interface TypeResolverBuilder<T extends TypeResolverBuilder<T>> 41 { 42 /* 43 /********************************************************** 44 /* Accessors 45 /********************************************************** 46 */ 47 48 /** 49 * Accessor for currently configured default type; implementation 50 * class that may be used in case no valid type information is 51 * available during type resolution 52 */ getDefaultImpl()53 public Class<?> getDefaultImpl(); 54 55 /* 56 /********************************************************** 57 /* Actual builder methods 58 /********************************************************** 59 */ 60 61 /** 62 * Method for building type serializer based on current configuration 63 * of this builder. 64 * 65 * @param baseType Base type that constructed resolver will 66 * handle; super type of all types it will be used for. 67 */ buildTypeSerializer(SerializationConfig config, JavaType baseType, Collection<NamedType> subtypes)68 public TypeSerializer buildTypeSerializer(SerializationConfig config, 69 JavaType baseType, Collection<NamedType> subtypes); 70 71 /** 72 * Method for building type deserializer based on current configuration 73 * of this builder. 74 * 75 * @param baseType Base type that constructed resolver will 76 * handle; super type of all types it will be used for. 77 * @param subtypes Known subtypes of the base type. 78 */ buildTypeDeserializer(DeserializationConfig config, JavaType baseType, Collection<NamedType> subtypes)79 public TypeDeserializer buildTypeDeserializer(DeserializationConfig config, 80 JavaType baseType, Collection<NamedType> subtypes); 81 82 /* 83 /********************************************************** 84 /* Initialization method(s) that must be called before other 85 /* configuration 86 /********************************************************** 87 */ 88 89 /** 90 * Initialization method that is called right after constructing 91 * the builder instance. 92 * 93 * @param idType Which type metadata is used 94 * @param res (optional) Custom type id resolver used, if any 95 * 96 * @return Resulting builder instance (usually this builder, 97 * but not necessarily) 98 */ init(JsonTypeInfo.Id idType, TypeIdResolver res)99 public T init(JsonTypeInfo.Id idType, TypeIdResolver res); 100 101 /* 102 /********************************************************** 103 /* Methods for configuring resolver to build 104 /********************************************************** 105 */ 106 107 /** 108 * Method for specifying mechanism to use for including type metadata 109 * in JSON. 110 * If not explicitly called, setting defaults to 111 * {@link As#PROPERTY}. 112 * 113 * @param includeAs Mechanism used for including type metadata in JSON 114 * 115 * @return Resulting builder instance (usually this builder, 116 * but may be a newly constructed instance for immutable builders} 117 */ inclusion(As includeAs)118 public T inclusion(As includeAs); 119 120 /** 121 * Method for specifying name of property used for including type 122 * information. Not used for all inclusion mechanisms; 123 * usually only used with {@link As#PROPERTY}. 124 *<p> 125 * If not explicitly called, name of property to use is based on 126 * defaults for {@link com.fasterxml.jackson.annotation.JsonTypeInfo.Id} configured. 127 * 128 * @param propName Name of JSON property to use for including 129 * type information 130 * 131 * @return Resulting builder instance (usually this builder, 132 * but may be a newly constructed instance for immutable builders} 133 */ typeProperty(String propName)134 public T typeProperty(String propName); 135 136 /** 137 * Method for specifying default implementation to use if type id 138 * is either not available, or cannot be resolved. 139 * 140 * @return Resulting builder instance (usually this builder, 141 * but may be a newly constructed instance for immutable builders} 142 */ defaultImpl(Class<?> defaultImpl)143 public T defaultImpl(Class<?> defaultImpl); 144 145 /** 146 * Method for specifying whether type id should be visible to 147 * {@link com.fasterxml.jackson.databind.JsonDeserializer}s or not. 148 * 149 * @return Resulting builder instance (usually this builder, 150 * but may be a newly constructed instance for immutable builders} 151 * 152 * @since 2.0 153 */ typeIdVisibility(boolean isVisible)154 public T typeIdVisibility(boolean isVisible); 155 } 156