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