http://github.com/FasterXML/jackson: General data-binding functionality for Jackson: works on core streaming API (FasterXML)
  • Tatu Saloranta
  • Christopher Currie
  • Paul Brown 
package com.fasterxml.jackson.databind;

import java.util.Collection;

import com.fasterxml.jackson.core.*;
import com.fasterxml.jackson.databind.cfg.MutableConfigOverride;
import com.fasterxml.jackson.databind.deser.BeanDeserializerModifier;
import com.fasterxml.jackson.databind.deser.DeserializationProblemHandler;
import com.fasterxml.jackson.databind.deser.Deserializers;
import com.fasterxml.jackson.databind.deser.KeyDeserializers;
import com.fasterxml.jackson.databind.deser.ValueInstantiators;
import com.fasterxml.jackson.databind.introspect.ClassIntrospector;
import com.fasterxml.jackson.databind.jsontype.NamedType;
import com.fasterxml.jackson.databind.ser.BeanSerializerModifier;
import com.fasterxml.jackson.databind.ser.Serializers;
import com.fasterxml.jackson.databind.type.TypeFactory;
import com.fasterxml.jackson.databind.type.TypeModifier;
import java.util.Collections;


Simple interface for extensions that can be registered with ObjectMapper to provide a well-defined set of extensions to default functionality; such as support for new data types. 
/**
 * Simple interface for extensions that can be registered with {@link ObjectMapper}
 * to provide a well-defined set of extensions to default functionality; such as
 * support for new data types.
 */
public abstract class Module
    implements Versioned
{
    /*
    /**********************************************************
    /* Simple accessors
    /**********************************************************
     */
    
    
Method that returns a display that can be used by Jackson
for informational purposes, as well as in associating extensions with
module that provides them.

/**
     * Method that returns a display that can be used by Jackson
     * for informational purposes, as well as in associating extensions with
     * module that provides them.
     */
    public abstract String getModuleName();

    
Method that returns version of this module. Can be used by Jackson for
informational purposes.

/**
     * Method that returns version of this module. Can be used by Jackson for
     * informational purposes.
     */
    @Override
    public abstract Version version();

    
Method that returns an id that may be used to determine if two Module instances are considered to be of same type, for purpose of preventing multiple registrations of "same type of" module (see MapperFeature.IGNORE_DUPLICATE_MODULE_REGISTRATIONS) If `null` is returned, every instance is considered unique. If non-null value is returned, equality of id Objects is used to check whether modules should be considered to be "of same type" 
 Default implementation returns value of class name (Class.getName). 
Since:2.5
/**
     * Method that returns an id that may be used to determine if two {@link Module}
     * instances are considered to be of same type, for purpose of preventing
     * multiple registrations of "same type of" module
     * (see {@link com.fasterxml.jackson.databind.MapperFeature#IGNORE_DUPLICATE_MODULE_REGISTRATIONS})
     * If `null` is returned, every instance is considered unique.
     * If non-null value is returned, equality of id Objects is used to check whether
     * modules should be considered to be "of same type"
     *<p>
     * Default implementation returns value of class name ({@link Class#getName}).
     *
     * @since 2.5
     */
    public Object getTypeId() {
        return getClass().getName();
    }
    
    /*
    /**********************************************************
    /* Life-cycle: registration
    /**********************************************************
     */
    
    
Method called by ObjectMapper when module is registered. It is called to let module register functionality it provides, using callback methods passed-in context object exposes. 
/**
     * Method called by {@link ObjectMapper} when module is registered.
     * It is called to let module register functionality it provides,
     * using callback methods passed-in context object exposes.
     */
    public abstract void setupModule(SetupContext context);

    
Returns the list of dependent modules this module has, if any.
It is called to let modules register other modules as dependencies.
Modules returned will be registered before this module is registered,
in iteration order.

Since:2.10
/**
     * Returns the list of dependent modules this module has, if any.
     * It is called to let modules register other modules as dependencies.
     * Modules returned will be registered before this module is registered,
     * in iteration order.
     *
     * @since 2.10
     */
    public Iterable<? extends Module> getDependencies() {
        return Collections.emptyList();
    }

    /*
    /**********************************************************
    /* Helper types
    /**********************************************************
     */

    
Interface Jackson exposes to modules for purpose of registering extended functionality. Usually implemented by ObjectMapper, but modules should NOT rely on this -- if they do require access to mapper instance, they need to call getOwner method. 
/**
     * Interface Jackson exposes to modules for purpose of registering
     * extended functionality.
     * Usually implemented by {@link ObjectMapper}, but modules should
     * NOT rely on this -- if they do require access to mapper instance,
     * they need to call {@link SetupContext#getOwner} method.
     */
    public static interface SetupContext
    {
        /*
        /**********************************************************
        /* Simple accessors
        /**********************************************************
         */
        
        
Method that returns version information about ObjectMapper that implements this context. Modules can use this to choose different settings or initialization order; or even decide to fail set up completely if version is compatible with module. 
/**
         * Method that returns version information about {@link ObjectMapper} 
         * that implements this context. Modules can use this to choose
         * different settings or initialization order; or even decide to fail
         * set up completely if version is compatible with module.
         */
        public Version getMapperVersion();

        
Fallback access method that allows modules to refer to the ObjectMapper that provided this context. It should NOT be needed by most modules; and ideally should not be used -- however, there may be cases where this may be necessary due to various design constraints. 

NOTE: use of this method is discouraged, as it allows access to
things Modules typically should not modify. It is included, however,
to allow access to new features in cases where Module API
has not yet been extended, or there are oversights.

 Return value is chosen to not leak dependency to ObjectMapper; however, instance will always be of that type. This is why return value is declared generic, to allow caller to specify context to often avoid casting. 
Since:2.0
/**
         * Fallback access method that allows modules to refer to the
         * {@link ObjectMapper} that provided this context.
         * It should NOT be needed by most modules; and ideally should
         * not be used -- however, there may be cases where this may
         * be necessary due to various design constraints.
         *<p>
         * NOTE: use of this method is discouraged, as it allows access to
         * things Modules typically should not modify. It is included, however,
         * to allow access to new features in cases where Module API
         * has not yet been extended, or there are oversights.
         *<p>
         * Return value is chosen to not leak dependency to {@link ObjectMapper};
         * however, instance will always be of that type.
         * This is why return value is declared generic, to allow caller to
         * specify context to often avoid casting.
         * 
         * @since 2.0
         */
        public <C extends ObjectCodec> C getOwner();

        
Accessor for finding TypeFactory that is currently configured by the context. 

NOTE: since it is possible that other modules might change or replace
TypeFactory, use of this method adds order-dependency for registrations.

Since:2.0
/**
         * Accessor for finding {@link TypeFactory} that is currently configured
         * by the context.
         *<p>
         * NOTE: since it is possible that other modules might change or replace
         * TypeFactory, use of this method adds order-dependency for registrations.
         * 
         * @since 2.0
         */
        public TypeFactory getTypeFactory();
        
        public boolean isEnabled(MapperFeature f);
        
        public boolean isEnabled(DeserializationFeature f);

        public boolean isEnabled(SerializationFeature f);

        public boolean isEnabled(JsonFactory.Feature f);
        
        public boolean isEnabled(JsonParser.Feature f);

        public boolean isEnabled(JsonGenerator.Feature f);

        /*
        /**********************************************************
        /* Mutant accessors
        /**********************************************************
         */

        
"Mutant accessor" for getting a mutable configuration override object for
given type, needed to add or change per-type overrides applied
to properties of given type.
Usage is through returned object by colling "setter" methods, which
directly modify override object and take effect directly.
For example you can do

  mapper.configOverride(java.util.Date.class)
      .setFormat(JsonFormat.Value.forPattern("yyyy-MM-dd"));

 to change the default format to use for properties of type Date (possibly further overridden by per-property annotations) 
Since:2.8
/**
         * "Mutant accessor" for getting a mutable configuration override object for
         * given type, needed to add or change per-type overrides applied
         * to properties of given type.
         * Usage is through returned object by colling "setter" methods, which
         * directly modify override object and take effect directly.
         * For example you can do
         *<pre>
         *   mapper.configOverride(java.util.Date.class)
         *       .setFormat(JsonFormat.Value.forPattern("yyyy-MM-dd"));
         *</pre>
         * to change the default format to use for properties of type
         * {@link java.util.Date} (possibly further overridden by per-property
         * annotations)
         *
         * @since 2.8
         */
        public MutableConfigOverride configOverride(Class<?> type);
        
        /*
        /**********************************************************
        /* Handler registration; serializers/deserializers
        /**********************************************************
         */
        
        
Method that module can use to register additional deserializers to use for
handling types.

Params:
  • d – Object that can be called to find deserializer for types supported
  by module (null returned for non-supported types)
/**
         * Method that module can use to register additional deserializers to use for
         * handling types.
         * 
         * @param d Object that can be called to find deserializer for types supported
         *   by module (null returned for non-supported types)
         */
        public void addDeserializers(Deserializers d);

        
Method that module can use to register additional deserializers to use for
handling Map key values (which are separate from value deserializers because
they are always serialized from String values)

/**
         * Method that module can use to register additional deserializers to use for
         * handling Map key values (which are separate from value deserializers because
         * they are always serialized from String values)
         */
        public void addKeyDeserializers(KeyDeserializers s);
        
        
Method that module can use to register additional serializers to use for
handling types.

Params:
  • s – Object that can be called to find serializer for types supported
  by module (null returned for non-supported types)
/**
         * Method that module can use to register additional serializers to use for
         * handling types.
         * 
         * @param s Object that can be called to find serializer for types supported
         *   by module (null returned for non-supported types)
         */
        public void addSerializers(Serializers s);

        
Method that module can use to register additional serializers to use for
handling Map key values (which are separate from value serializers because
they must write JsonToken.FIELD_NAME instead of String value).

/**
         * Method that module can use to register additional serializers to use for
         * handling Map key values (which are separate from value serializers because
         * they must write <code>JsonToken.FIELD_NAME</code> instead of String value).
         */
        public void addKeySerializers(Serializers s);

        /*
        /**********************************************************
        /* Handler registration; other
        /**********************************************************
         */
        
        
Method that module can use to register additional modifier objects to
customize configuration and construction of bean deserializers.

Params:
  • mod – Modifier to register
/**
         * Method that module can use to register additional modifier objects to
         * customize configuration and construction of bean deserializers.
         * 
         * @param mod Modifier to register
         */
        public void addBeanDeserializerModifier(BeanDeserializerModifier mod);

        
Method that module can use to register additional modifier objects to
customize configuration and construction of bean serializers.

Params:
  • mod – Modifier to register
/**
         * Method that module can use to register additional modifier objects to
         * customize configuration and construction of bean serializers.
         * 
         * @param mod Modifier to register
         */
        public void addBeanSerializerModifier(BeanSerializerModifier mod);

        
Method that module can use to register additional AbstractTypeResolver instance, to handle resolution of abstract to concrete types (either by defaulting, or by materializing). 
Params:
  • resolver – Resolver to add.
/**
         * Method that module can use to register additional
         * {@link AbstractTypeResolver} instance, to handle resolution of
         * abstract to concrete types (either by defaulting, or by materializing).
         * 
         * @param resolver Resolver to add.
         */
        public void addAbstractTypeResolver(AbstractTypeResolver resolver);

        
Method that module can use to register additional TypeModifier instance, which can augment JavaType instances constructed by TypeFactory. 
Params:
  • modifier – to add
/**
         * Method that module can use to register additional
         * {@link TypeModifier} instance, which can augment {@link com.fasterxml.jackson.databind.JavaType}
         * instances constructed by {@link com.fasterxml.jackson.databind.type.TypeFactory}.
         * 
         * @param modifier to add
         */
        public void addTypeModifier(TypeModifier modifier);

        
Method that module can use to register additional ValueInstantiators, by adding ValueInstantiators object that gets called when instantatiator is needed by a deserializer. 
Params:
  • instantiators – Object that can provide ValueInstantiators for constructing POJO values during deserialization
/**
         * Method that module can use to register additional {@link com.fasterxml.jackson.databind.deser.ValueInstantiator}s,
         * by adding {@link ValueInstantiators} object that gets called when 
         * instantatiator is needed by a deserializer.
         * 
         * @param instantiators Object that can provide {@link com.fasterxml.jackson.databind.deser.ValueInstantiator}s for
         *    constructing POJO values during deserialization
         */
        public void addValueInstantiators(ValueInstantiators instantiators);

        
Method for replacing the default class introspector with a derived class that
overrides specific behavior.

Params:
  • ci – Derived class of ClassIntrospector with overriden behavior
Since:2.2
/**
         * Method for replacing the default class introspector with a derived class that
         * overrides specific behavior.
         *
         * @param ci Derived class of ClassIntrospector with overriden behavior
         *
         * @since 2.2
         */
        public void setClassIntrospector(ClassIntrospector ci);

        
Method for registering specified AnnotationIntrospector as the highest priority introspector (will be chained with existing introspector(s) which will be used as fallbacks for cases this introspector does not handle) 
Params:
  • ai – Annotation introspector to register.
/**
         * Method for registering specified {@link AnnotationIntrospector} as the highest
         * priority introspector (will be chained with existing introspector(s) which
         * will be used as fallbacks for cases this introspector does not handle)
         * 
         * @param ai Annotation introspector to register.
         */
        public void insertAnnotationIntrospector(AnnotationIntrospector ai);

        
Method for registering specified AnnotationIntrospector as the lowest priority introspector, chained with existing introspector(s) and called as fallback for cases not otherwise handled. 
Params:
  • ai – Annotation introspector to register.
/**
         * Method for registering specified {@link AnnotationIntrospector} as the lowest
         * priority introspector, chained with existing introspector(s) and called
         * as fallback for cases not otherwise handled.
         * 
         * @param ai Annotation introspector to register.
         */
        public void appendAnnotationIntrospector(AnnotationIntrospector ai);

        
Method for registering specified classes as subtypes (of supertype(s)
they have)

/**
         * Method for registering specified classes as subtypes (of supertype(s)
         * they have)
         */
        public void registerSubtypes(Class<?>... subtypes);

        
Method for registering specified classes as subtypes (of supertype(s)
they have), using specified type names.

/**
         * Method for registering specified classes as subtypes (of supertype(s)
         * they have), using specified type names.
         */
        public void registerSubtypes(NamedType... subtypes);

        
Method for registering specified classes as subtypes (of supertype(s)
they have)

Since:2.9
/**
         * Method for registering specified classes as subtypes (of supertype(s)
         * they have)
         *
         * @since 2.9
         */
        public void registerSubtypes(Collection<Class<?>> subtypes);
        
        
Method used for defining mix-in annotations to use for augmenting
specified class or interface.
All annotations from
mixinSource are taken to override annotations
that target (or its supertypes) has.


Note: mix-ins are registered both for serialization and deserialization
(which can be different internally).


Note: currently only one set of mix-in annotations can be defined for
a single class; so if multiple modules register mix-ins, highest
priority one (last one registered) will have priority over other modules.

Params:
  • target – Class (or interface) whose annotations to effectively override
  • mixinSource – Class (or interface) whose annotations are to
  be "added" to target's annotations, overriding as necessary
/**
         * Method used for defining mix-in annotations to use for augmenting
         * specified class or interface.
         * All annotations from
         * <code>mixinSource</code> are taken to override annotations
         * that <code>target</code> (or its supertypes) has.
         *<p>
         * Note: mix-ins are registered both for serialization and deserialization
         * (which can be different internally).
         *<p>
         * Note: currently only one set of mix-in annotations can be defined for
         * a single class; so if multiple modules register mix-ins, highest
         * priority one (last one registered) will have priority over other modules.
         *
         * @param target Class (or interface) whose annotations to effectively override
         * @param mixinSource Class (or interface) whose annotations are to
         *   be "added" to target's annotations, overriding as necessary
         */
        public void setMixInAnnotations(Class<?> target, Class<?> mixinSource);

        
Add a deserialization problem handler

Params:
  • handler – The deserialization problem handler
/**
         * Add a deserialization problem handler
         *
         * @param handler The deserialization problem handler
         */
        public void addDeserializationProblemHandler(DeserializationProblemHandler handler);

        
Method that may be used to override naming strategy that is used by ObjectMapper. 
Since:2.3
/**
         * Method that may be used to override naming strategy that is used
         * by {@link ObjectMapper}.
         * 
         * @since 2.3
         */
        public void setNamingStrategy(PropertyNamingStrategy naming);
    }
}