1 package com.fasterxml.jackson.databind; 2 3 import java.util.Collection; 4 5 import com.fasterxml.jackson.core.*; 6 import com.fasterxml.jackson.databind.cfg.MutableConfigOverride; 7 import com.fasterxml.jackson.databind.deser.BeanDeserializerModifier; 8 import com.fasterxml.jackson.databind.deser.DeserializationProblemHandler; 9 import com.fasterxml.jackson.databind.deser.Deserializers; 10 import com.fasterxml.jackson.databind.deser.KeyDeserializers; 11 import com.fasterxml.jackson.databind.deser.ValueInstantiators; 12 import com.fasterxml.jackson.databind.introspect.ClassIntrospector; 13 import com.fasterxml.jackson.databind.jsontype.NamedType; 14 import com.fasterxml.jackson.databind.ser.BeanSerializerModifier; 15 import com.fasterxml.jackson.databind.ser.Serializers; 16 import com.fasterxml.jackson.databind.type.TypeFactory; 17 import com.fasterxml.jackson.databind.type.TypeModifier; 18 import java.util.Collections; 19 20 /** 21 * Simple interface for extensions that can be registered with {@link ObjectMapper} 22 * to provide a well-defined set of extensions to default functionality; such as 23 * support for new data types. 24 */ 25 public abstract class Module 26 implements Versioned 27 { 28 /* 29 /********************************************************** 30 /* Simple accessors 31 /********************************************************** 32 */ 33 34 /** 35 * Method that returns a display that can be used by Jackson 36 * for informational purposes, as well as in associating extensions with 37 * module that provides them. 38 */ getModuleName()39 public abstract String getModuleName(); 40 41 /** 42 * Method that returns version of this module. Can be used by Jackson for 43 * informational purposes. 44 */ 45 @Override version()46 public abstract Version version(); 47 48 /** 49 * Method that returns an id that may be used to determine if two {@link Module} 50 * instances are considered to be of same type, for purpose of preventing 51 * multiple registrations of "same type of" module 52 * (see {@link com.fasterxml.jackson.databind.MapperFeature#IGNORE_DUPLICATE_MODULE_REGISTRATIONS}) 53 * If `null` is returned, every instance is considered unique. 54 * If non-null value is returned, equality of id Objects is used to check whether 55 * modules should be considered to be "of same type" 56 *<p> 57 * Default implementation returns value of class name ({@link Class#getName}). 58 * 59 * @since 2.5 60 */ getTypeId()61 public Object getTypeId() { 62 return getClass().getName(); 63 } 64 65 /* 66 /********************************************************** 67 /* Life-cycle: registration 68 /********************************************************** 69 */ 70 71 /** 72 * Method called by {@link ObjectMapper} when module is registered. 73 * It is called to let module register functionality it provides, 74 * using callback methods passed-in context object exposes. 75 */ setupModule(SetupContext context)76 public abstract void setupModule(SetupContext context); 77 78 /** 79 * Returns the list of dependent modules this module has, if any. 80 * It is called to let modules register other modules as dependencies. 81 * Modules returned will be registered before this module is registered, 82 * in iteration order. 83 * 84 * @since 2.10 85 */ getDependencies()86 public Iterable<? extends Module> getDependencies() { 87 return Collections.emptyList(); 88 } 89 90 /* 91 /********************************************************** 92 /* Helper types 93 /********************************************************** 94 */ 95 96 /** 97 * Interface Jackson exposes to modules for purpose of registering 98 * extended functionality. 99 * Usually implemented by {@link ObjectMapper}, but modules should 100 * NOT rely on this -- if they do require access to mapper instance, 101 * they need to call {@link SetupContext#getOwner} method. 102 */ 103 public static interface SetupContext 104 { 105 /* 106 /********************************************************** 107 /* Simple accessors 108 /********************************************************** 109 */ 110 111 /** 112 * Method that returns version information about {@link ObjectMapper} 113 * that implements this context. Modules can use this to choose 114 * different settings or initialization order; or even decide to fail 115 * set up completely if version is compatible with module. 116 */ getMapperVersion()117 public Version getMapperVersion(); 118 119 /** 120 * Fallback access method that allows modules to refer to the 121 * {@link ObjectMapper} that provided this context. 122 * It should NOT be needed by most modules; and ideally should 123 * not be used -- however, there may be cases where this may 124 * be necessary due to various design constraints. 125 *<p> 126 * NOTE: use of this method is discouraged, as it allows access to 127 * things Modules typically should not modify. It is included, however, 128 * to allow access to new features in cases where Module API 129 * has not yet been extended, or there are oversights. 130 *<p> 131 * Return value is chosen to not leak dependency to {@link ObjectMapper}; 132 * however, instance will always be of that type. 133 * This is why return value is declared generic, to allow caller to 134 * specify context to often avoid casting. 135 * 136 * @since 2.0 137 */ getOwner()138 public <C extends ObjectCodec> C getOwner(); 139 140 /** 141 * Accessor for finding {@link TypeFactory} that is currently configured 142 * by the context. 143 *<p> 144 * NOTE: since it is possible that other modules might change or replace 145 * TypeFactory, use of this method adds order-dependency for registrations. 146 * 147 * @since 2.0 148 */ getTypeFactory()149 public TypeFactory getTypeFactory(); 150 isEnabled(MapperFeature f)151 public boolean isEnabled(MapperFeature f); 152 isEnabled(DeserializationFeature f)153 public boolean isEnabled(DeserializationFeature f); 154 isEnabled(SerializationFeature f)155 public boolean isEnabled(SerializationFeature f); 156 isEnabled(JsonFactory.Feature f)157 public boolean isEnabled(JsonFactory.Feature f); 158 isEnabled(JsonParser.Feature f)159 public boolean isEnabled(JsonParser.Feature f); 160 isEnabled(JsonGenerator.Feature f)161 public boolean isEnabled(JsonGenerator.Feature f); 162 163 /* 164 /********************************************************** 165 /* Mutant accessors 166 /********************************************************** 167 */ 168 169 /** 170 * "Mutant accessor" for getting a mutable configuration override object for 171 * given type, needed to add or change per-type overrides applied 172 * to properties of given type. 173 * Usage is through returned object by colling "setter" methods, which 174 * directly modify override object and take effect directly. 175 * For example you can do 176 *<pre> 177 * mapper.configOverride(java.util.Date.class) 178 * .setFormat(JsonFormat.Value.forPattern("yyyy-MM-dd")); 179 *</pre> 180 * to change the default format to use for properties of type 181 * {@link java.util.Date} (possibly further overridden by per-property 182 * annotations) 183 * 184 * @since 2.8 185 */ configOverride(Class<?> type)186 public MutableConfigOverride configOverride(Class<?> type); 187 188 /* 189 /********************************************************** 190 /* Handler registration; serializers/deserializers 191 /********************************************************** 192 */ 193 194 /** 195 * Method that module can use to register additional deserializers to use for 196 * handling types. 197 * 198 * @param d Object that can be called to find deserializer for types supported 199 * by module (null returned for non-supported types) 200 */ addDeserializers(Deserializers d)201 public void addDeserializers(Deserializers d); 202 203 /** 204 * Method that module can use to register additional deserializers to use for 205 * handling Map key values (which are separate from value deserializers because 206 * they are always serialized from String values) 207 */ addKeyDeserializers(KeyDeserializers s)208 public void addKeyDeserializers(KeyDeserializers s); 209 210 /** 211 * Method that module can use to register additional serializers to use for 212 * handling types. 213 * 214 * @param s Object that can be called to find serializer for types supported 215 * by module (null returned for non-supported types) 216 */ addSerializers(Serializers s)217 public void addSerializers(Serializers s); 218 219 /** 220 * Method that module can use to register additional serializers to use for 221 * handling Map key values (which are separate from value serializers because 222 * they must write <code>JsonToken.FIELD_NAME</code> instead of String value). 223 */ addKeySerializers(Serializers s)224 public void addKeySerializers(Serializers s); 225 226 /* 227 /********************************************************** 228 /* Handler registration; other 229 /********************************************************** 230 */ 231 232 /** 233 * Method that module can use to register additional modifier objects to 234 * customize configuration and construction of bean deserializers. 235 * 236 * @param mod Modifier to register 237 */ addBeanDeserializerModifier(BeanDeserializerModifier mod)238 public void addBeanDeserializerModifier(BeanDeserializerModifier mod); 239 240 /** 241 * Method that module can use to register additional modifier objects to 242 * customize configuration and construction of bean serializers. 243 * 244 * @param mod Modifier to register 245 */ addBeanSerializerModifier(BeanSerializerModifier mod)246 public void addBeanSerializerModifier(BeanSerializerModifier mod); 247 248 /** 249 * Method that module can use to register additional 250 * {@link AbstractTypeResolver} instance, to handle resolution of 251 * abstract to concrete types (either by defaulting, or by materializing). 252 * 253 * @param resolver Resolver to add. 254 */ addAbstractTypeResolver(AbstractTypeResolver resolver)255 public void addAbstractTypeResolver(AbstractTypeResolver resolver); 256 257 /** 258 * Method that module can use to register additional 259 * {@link TypeModifier} instance, which can augment {@link com.fasterxml.jackson.databind.JavaType} 260 * instances constructed by {@link com.fasterxml.jackson.databind.type.TypeFactory}. 261 * 262 * @param modifier to add 263 */ addTypeModifier(TypeModifier modifier)264 public void addTypeModifier(TypeModifier modifier); 265 266 /** 267 * Method that module can use to register additional {@link com.fasterxml.jackson.databind.deser.ValueInstantiator}s, 268 * by adding {@link ValueInstantiators} object that gets called when 269 * instantatiator is needed by a deserializer. 270 * 271 * @param instantiators Object that can provide {@link com.fasterxml.jackson.databind.deser.ValueInstantiator}s for 272 * constructing POJO values during deserialization 273 */ addValueInstantiators(ValueInstantiators instantiators)274 public void addValueInstantiators(ValueInstantiators instantiators); 275 276 /** 277 * Method for replacing the default class introspector with a derived class that 278 * overrides specific behavior. 279 * 280 * @param ci Derived class of ClassIntrospector with overriden behavior 281 * 282 * @since 2.2 283 */ setClassIntrospector(ClassIntrospector ci)284 public void setClassIntrospector(ClassIntrospector ci); 285 286 /** 287 * Method for registering specified {@link AnnotationIntrospector} as the highest 288 * priority introspector (will be chained with existing introspector(s) which 289 * will be used as fallbacks for cases this introspector does not handle) 290 * 291 * @param ai Annotation introspector to register. 292 */ insertAnnotationIntrospector(AnnotationIntrospector ai)293 public void insertAnnotationIntrospector(AnnotationIntrospector ai); 294 295 /** 296 * Method for registering specified {@link AnnotationIntrospector} as the lowest 297 * priority introspector, chained with existing introspector(s) and called 298 * as fallback for cases not otherwise handled. 299 * 300 * @param ai Annotation introspector to register. 301 */ appendAnnotationIntrospector(AnnotationIntrospector ai)302 public void appendAnnotationIntrospector(AnnotationIntrospector ai); 303 304 /** 305 * Method for registering specified classes as subtypes (of supertype(s) 306 * they have) 307 */ registerSubtypes(Class<?>.... subtypes)308 public void registerSubtypes(Class<?>... subtypes); 309 310 /** 311 * Method for registering specified classes as subtypes (of supertype(s) 312 * they have), using specified type names. 313 */ registerSubtypes(NamedType... subtypes)314 public void registerSubtypes(NamedType... subtypes); 315 316 /** 317 * Method for registering specified classes as subtypes (of supertype(s) 318 * they have) 319 * 320 * @since 2.9 321 */ registerSubtypes(Collection<Class<?>> subtypes)322 public void registerSubtypes(Collection<Class<?>> subtypes); 323 324 /** 325 * Method used for defining mix-in annotations to use for augmenting 326 * specified class or interface. 327 * All annotations from 328 * <code>mixinSource</code> are taken to override annotations 329 * that <code>target</code> (or its supertypes) has. 330 *<p> 331 * Note: mix-ins are registered both for serialization and deserialization 332 * (which can be different internally). 333 *<p> 334 * Note: currently only one set of mix-in annotations can be defined for 335 * a single class; so if multiple modules register mix-ins, highest 336 * priority one (last one registered) will have priority over other modules. 337 * 338 * @param target Class (or interface) whose annotations to effectively override 339 * @param mixinSource Class (or interface) whose annotations are to 340 * be "added" to target's annotations, overriding as necessary 341 */ setMixInAnnotations(Class<?> target, Class<?> mixinSource)342 public void setMixInAnnotations(Class<?> target, Class<?> mixinSource); 343 344 /** 345 * Add a deserialization problem handler 346 * 347 * @param handler The deserialization problem handler 348 */ addDeserializationProblemHandler(DeserializationProblemHandler handler)349 public void addDeserializationProblemHandler(DeserializationProblemHandler handler); 350 351 /** 352 * Method that may be used to override naming strategy that is used 353 * by {@link ObjectMapper}. 354 * 355 * @since 2.3 356 */ setNamingStrategy(PropertyNamingStrategy naming)357 public void setNamingStrategy(PropertyNamingStrategy naming); 358 } 359 } 360