| 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 {@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. |
| */ |
| public abstract String getModuleName(); |
| |
| /** |
| * 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 {@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 {@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 |
| */ |
| public Iterable<? extends Module> getDependencies() { |
| return Collections.emptyList(); |
| } |
| |
| /* |
| /********************************************************** |
| /* Helper types |
| /********************************************************** |
| */ |
| |
| /** |
| * 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 {@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 |
| * {@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 {@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 |
| *<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. |
| * |
| * @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) |
| */ |
| public void addKeyDeserializers(KeyDeserializers s); |
| |
| /** |
| * 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 <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. |
| * |
| * @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. |
| * |
| * @param mod Modifier to register |
| */ |
| public void addBeanSerializerModifier(BeanSerializerModifier mod); |
| |
| /** |
| * 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 |
| * {@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 {@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. |
| * |
| * @param ci Derived class of ClassIntrospector with overriden behavior |
| * |
| * @since 2.2 |
| */ |
| public void setClassIntrospector(ClassIntrospector ci); |
| |
| /** |
| * 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 {@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) |
| */ |
| public void registerSubtypes(Class<?>... subtypes); |
| |
| /** |
| * 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 |
| */ |
| public void registerSubtypes(Collection<Class<?>> subtypes); |
| |
| /** |
| * 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 |
| * |
| * @param handler The deserialization problem handler |
| */ |
| public void addDeserializationProblemHandler(DeserializationProblemHandler handler); |
| |
| /** |
| * Method that may be used to override naming strategy that is used |
| * by {@link ObjectMapper}. |
| * |
| * @since 2.3 |
| */ |
| public void setNamingStrategy(PropertyNamingStrategy naming); |
| } |
| } |