CustomSerializerFactory (Jackson JSON Processor)
Date: 2013-07-14

org.codehaus.jackson.map.ser

## Class CustomSerializerFactory

- java.lang.Object
- - org.codehaus.jackson.map.SerializerFactory
  - - org.codehaus.jackson.map.ser.BasicSerializerFactory
    - - org.codehaus.jackson.map.ser.BeanSerializerFactory
      - - org.codehaus.jackson.map.ser.CustomSerializerFactory

-     public class CustomSerializerFactory
      extends BeanSerializerFactory

  Serializer factory implementation that allows for configuring mapping between types (classes) and serializers to use, by using multiple types of overrides. Existing mappings established by `BeanSerializerFactory` (and its super class, `BasicSerializerFactory`) are used if no overrides are defined.

  Unlike base serializer factories (`BasicSerializerFactory`, `BeanSerializerFactory`), this factory is stateful because of configuration settings. It is thread-safe, however, as long as all configuration as done before using the factory -- a single instance can be shared between providers and mappers.

  Configurations currently available are:

  - Ability to define explicit mappings between classes and interfaces and serializers to use. These can be either specific ones (class must match exactly) or generic ones (any sub-class or class implementing the interface); specific ones have precedence over generic ones (and precedence between generic ones is not defined).
  - Ability to define a single generic base serializer for all Enum types (precedence below specific serializer mapping)

  Note: as of version 1.7, this class is not as useful as it used to be, due to addition of "modules", which allow simpler addition of custom serializers and deserializers. In fact, use of module system is recommended even when not exposing serializers or deserializers as a pluggable library (just using them locally).

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.codehaus.jackson.map.ser.BeanSerializerFactory

      `BeanSerializerFactory.ConfigImpl`

    - ### Nested classes/interfaces inherited from class org.codehaus.jackson.map.SerializerFactory

      `SerializerFactory.Config`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected HashMap<ClassKey,JsonSerializer<?>>` | `_directClassMappings` Direct mappings that are only used for exact class type matches, but not for sub-class checks.
    `protected JsonSerializer<?>` | `_enumSerializerOverride` And for Enum handling we may specify a single default serializer to use, regardless of actual enumeration.
    `protected HashMap<ClassKey,JsonSerializer<?>>` | `_interfaceMappings` And finally interface-based matches.
    `protected HashMap<ClassKey,JsonSerializer<?>>` | `_transitiveClassMappings` And then class-based mappings that are used both for exact and sub-class matches.

    - ### Fields inherited from class org.codehaus.jackson.map.ser.BeanSerializerFactory

      `_factoryConfig, instance`

    - ### Fields inherited from class org.codehaus.jackson.map.ser.BasicSerializerFactory

      `_arraySerializers, _concrete, _concreteLazy, optionalHandlers`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CustomSerializerFactory()`
    `CustomSerializerFactory(SerializerFactory.Config config)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected JsonSerializer<?>` | `_findInterfaceMapping(Class<?> cls, ClassKey key)`
    `<T> void` | `addGenericMapping(Class<? extends T> type, JsonSerializer<T> ser)` Method used to add a generic (transitive) mapping from specified class or its sub-classes into a serializer.
    `<T> void` | `addSpecificMapping(Class<? extends T> forClass, JsonSerializer<T> ser)` Method used to add a mapping from specific type -- and only that type -- to specified serializer.
    `JsonSerializer<Object>` | `createSerializer(SerializationConfig config, JavaType type, BeanProperty property)` Main serializer constructor method.
    `protected JsonSerializer<?>` | `findCustomSerializer(Class<?> type, SerializationConfig config)`
    `void` | `setEnumSerializer(JsonSerializer<?> enumSer)` Method that can be used to force specified serializer to be used for serializing all Enum instances.
    `SerializerFactory` | `withConfig(SerializerFactory.Config config)` Method used by module registration functionality, to attach additional serializer providers into this serializer factory.

    - ### Methods inherited from class org.codehaus.jackson.map.ser.BeanSerializerFactory

      `_constructWriter, constructBeanSerializer, constructBeanSerializerBuilder, constructFilteredBeanWriter, constructPropertyBuilder, createKeySerializer, customSerializers, filterBeanProperties, findBeanProperties, findBeanSerializer, findFilterId, findPropertyContentTypeSerializer, findPropertyTypeSerializer, getConfig, isPotentialBeanType, processViews, removeIgnorableTypes, removeSetterlessGetters, sortBeanProperties`

    - ### Methods inherited from class org.codehaus.jackson.map.ser.BasicSerializerFactory

      `buildArraySerializer, buildCollectionLikeSerializer, buildCollectionSerializer, buildContainerSerializer, buildEnumMapSerializer, buildEnumSetSerializer, buildIterableSerializer, buildIteratorSerializer, buildMapLikeSerializer, buildMapSerializer, createTypeSerializer, findContentSerializer, findKeySerializer, findSerializerByAddonType, findSerializerByLookup, findSerializerByPrimaryType, findSerializerFromAnnotation, getNullSerializer, isIndexedList, modifySecondaryTypesByAnnotation, modifyTypeByAnnotation, usesStaticTyping`

    - ### Methods inherited from class org.codehaus.jackson.map.SerializerFactory

      `createSerializer, createTypeSerializer, withAdditionalKeySerializers, withAdditionalSerializers, withSerializerModifier`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### _directClassMappings

          protected HashMap<ClassKey,JsonSerializer<?>> _directClassMappings

      Direct mappings that are only used for exact class type matches, but not for sub-class checks.

    - #### _enumSerializerOverride

          protected JsonSerializer<?> _enumSerializerOverride

      And for Enum handling we may specify a single default serializer to use, regardless of actual enumeration. Usually used to provide "toString - serializer".

    - #### _transitiveClassMappings

          protected HashMap<ClassKey,JsonSerializer<?>> _transitiveClassMappings

      And then class-based mappings that are used both for exact and sub-class matches.

    - #### _interfaceMappings

          protected HashMap<ClassKey,JsonSerializer<?>> _interfaceMappings

      And finally interface-based matches.

  - ### Constructor Detail

    - #### CustomSerializerFactory

          public CustomSerializerFactory()

    - #### CustomSerializerFactory

          public CustomSerializerFactory(SerializerFactory.Config config)

  - ### Method Detail

    - #### withConfig

          public SerializerFactory withConfig(SerializerFactory.Config config)

      Description copied from class: `BeanSerializerFactory`
      Method used by module registration functionality, to attach additional serializer providers into this serializer factory. This is typically handled by constructing a new instance with additional serializers, to ensure thread-safe access.
      Overrides:
        `withConfig` in class `BeanSerializerFactory`

    - #### addGenericMapping

          public <T> void addGenericMapping(Class<? extends T> type,
                                   JsonSerializer<T> ser)

      Method used to add a generic (transitive) mapping from specified class or its sub-classes into a serializer. When resolving a type into a serializer, explicit class is checked first, then immediate super-class, and so forth along inheritance chain. But if this fails, implemented interfaces are checked; ordering is done such that first interfaces implemented by the exact type are checked (in order returned by `Class.getInterfaces()`), then super-type's and so forth.

      Note that adding generic mappings may lead to problems with sub-classing: if sub-classes add new properties, these may not get properly serialized.

      Parameters:
        `type` - Class for which specified serializer is to be used. May be more specific type than what serializer indicates, but must be compatible (same or sub-class)

    - #### addSpecificMapping

          public <T> void addSpecificMapping(Class<? extends T> forClass,
                                    JsonSerializer<T> ser)

      Method used to add a mapping from specific type -- and only that type -- to specified serializer. This means that binding is not used for sub-types. It also means that no such mappings are to be defined for abstract classes or interfaces: and if an attempt is made, `IllegalArgumentException` will be thrown to indicate caller error.
      Parameters:
        `forClass` - Class for which specified serializer is to be used. May be more specific type than what serializer indicates, but must be compatible (same or sub-class)

    - #### setEnumSerializer

          public void setEnumSerializer(JsonSerializer<?> enumSer)

      Method that can be used to force specified serializer to be used for serializing all Enum instances. This is most commonly used to specify serializers that call either `enum.toString()`, or modify value returned by `enum.name()` (such as upper- or lower-casing it).

      Note: this serializer has lower precedence than that of specific types; so if a specific serializer is assigned to an Enum type, this serializer will NOT be used. It has higher precedence than generic mappings have however.

    - #### createSerializer

          public JsonSerializer<Object> createSerializer(SerializationConfig config,
                                                JavaType type,
                                                BeanProperty property)
                                                  throws JsonMappingException

      Description copied from class: `BeanSerializerFactory`
      Main serializer constructor method. We will have to be careful with respect to ordering of various method calls: essentially we want to reliably figure out which classes are standard types, and which are beans. The problem is that some bean Classes may implement standard interfaces (say, `Iterable`.

      Note: sub-classes may choose to complete replace implementation, if they want to alter priority of serializer lookups.

      Overrides:
        `createSerializer` in class `BeanSerializerFactory`
      Throws:
        `JsonMappingException`

    - #### findCustomSerializer

          protected JsonSerializer<?> findCustomSerializer(Class<?> type,
                                               SerializationConfig config)

    - #### _findInterfaceMapping

          protected JsonSerializer<?> _findInterfaceMapping(Class<?> cls,
                                                ClassKey key)