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

org.codehaus.jackson.map

## Class SerializerProvider

- java.lang.Object
- - org.codehaus.jackson.map.SerializerProvider

- Direct Known Subclasses:
    StdSerializerProvider

      public abstract class SerializerProvider
      extends Object

  Abstract class that defines API used by `ObjectMapper` and `JsonSerializer`s to obtain serializers capable of serializing instances of specific types.

  Note about usage: for `JsonSerializer` instances, only accessors for locating other (sub-)serializers are to be used. `ObjectMapper`, on the other hand, is to initialize recursive serialization process by calling `serializeValue(org.codehaus.jackson.map.SerializationConfig, org.codehaus.jackson.JsonGenerator, java.lang.Object, org.codehaus.jackson.map.SerializerFactory)`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected SerializationConfig` | `_config` Serialization configuration to use for serialization processing.
    `protected Class<?>` | `_serializationView` View used for currently active serialization
    `protected static JavaType` | `TYPE_OBJECT`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SerializerProvider(SerializationConfig config)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract int` | `cachedSerializersCount()` Method that can be used to determine how many serializers this provider is caching currently (if it does caching: default implementation does) Exact count depends on what kind of serializers get cached; default implementation caches all serializers, including ones that are eagerly constructed (for optimal access speed)
    `JavaType` | `constructSpecializedType(JavaType baseType, Class<?> subclass)`
    `JavaType` | `constructType(Type type)`
    `abstract void` | `defaultSerializeDateKey(Date date, JsonGenerator jgen)` Method that will handle serialization of Dates used as `Map` keys, based on `SerializationConfig.Feature.WRITE_DATE_KEYS_AS_TIMESTAMPS` value (and if using textual representation, configured date format)
    `abstract void` | `defaultSerializeDateKey(long timestamp, JsonGenerator jgen)` Method that will handle serialization of Dates used as `Map` keys, based on `SerializationConfig.Feature.WRITE_DATE_KEYS_AS_TIMESTAMPS` value (and if using textual representation, configured date format)
    `abstract void` | `defaultSerializeDateValue(Date date, JsonGenerator jgen)` Method that will handle serialization of Date(-like) values, using `SerializationConfig` settings to determine expected serialization behavior.
    `abstract void` | `defaultSerializeDateValue(long timestamp, JsonGenerator jgen)` Method that will handle serialization of Date(-like) values, using `SerializationConfig` settings to determine expected serialization behavior.
    `void` | `defaultSerializeField(String fieldName, Object value, JsonGenerator jgen)` Convenience method that will serialize given field with specified value.
    `void` | `defaultSerializeNull(JsonGenerator jgen)`
    `void` | `defaultSerializeValue(Object value, JsonGenerator jgen)` Convenience method that will serialize given value (which can be null) using standard serializer locating functionality.
    `abstract JsonSerializer<Object>` | `findKeySerializer(JavaType keyType, BeanProperty property)` Method called to get the serializer to use for serializing non-null Map keys.
    `JsonSerializer<Object>` | `findTypedValueSerializer(Class<?> valueType, boolean cache)` Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
    `abstract JsonSerializer<Object>` | `findTypedValueSerializer(Class<?> valueType, boolean cache, BeanProperty property)` Method called to locate regular serializer, matching type serializer, and if both found, wrap them in a serializer that calls both in correct sequence.
    `JsonSerializer<Object>` | `findTypedValueSerializer(JavaType valueType, boolean cache)` Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
    `abstract JsonSerializer<Object>` | `findTypedValueSerializer(JavaType valueType, boolean cache, BeanProperty property)` Method called to locate regular serializer, matching type serializer, and if both found, wrap them in a serializer that calls both in correct sequence.
    `JsonSerializer<Object>` | `findValueSerializer(Class<?> runtimeType)` Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
    `abstract JsonSerializer<Object>` | `findValueSerializer(Class<?> runtimeType, BeanProperty property)` Method called to get hold of a serializer for a value of given type; or if no such serializer can be found, a default handler (which may do a best-effort generic serialization or just simply throw an exception when invoked).
    `JsonSerializer<Object>` | `findValueSerializer(JavaType serializationType)` Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
    `abstract JsonSerializer<Object>` | `findValueSerializer(JavaType serializationType, BeanProperty property)` Similar to `findValueSerializer(Class)`, but takes full generics-aware type instead of raw class.
    `abstract void` | `flushCachedSerializers()` Method that will drop all serializers currently cached by this provider.
    `abstract JsonSchema` | `generateJsonSchema(Class<?> type, SerializationConfig config, SerializerFactory jsf)` Generate Json-schema for given type.
    `SerializationConfig` | `getConfig()` Method for accessing configuration for the serialization processing.
    `FilterProvider` | `getFilterProvider()` Convenience method for accessing provider to find serialization filters used, equivalent to calling:
    `JsonSerializer<Object>` | `getKeySerializer()` Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
    `JsonSerializer<Object>` | `getKeySerializer(JavaType valueType, BeanProperty property)` Deprecated. As of version 1.8
    `abstract JsonSerializer<Object>` | `getNullKeySerializer()` Method called to get the serializer to use for serializing Map keys that are nulls: this is needed since JSON does not allow any non-String value as key, including null.
    `abstract JsonSerializer<Object>` | `getNullValueSerializer()` Method called to get the serializer to use for serializing values (root level, Array members or List field values) that are nulls.
    `Class<?>` | `getSerializationView()` Convenience method for accessing serialization view in use (if any); equivalent to:
    `abstract JsonSerializer<Object>` | `getUnknownTypeSerializer(Class<?> unknownType)` Method called to get the serializer to use if provider can not determine an actual type-specific serializer to use; typically when none of `SerializerFactory` instances are able to construct a serializer.
    `abstract boolean` | `hasSerializerFor(SerializationConfig cfg, Class<?> cls, SerializerFactory jsf)` Method that can be called to see if this serializer provider can find a serializer for an instance of given class.
    `boolean` | `isEnabled(SerializationConfig.Feature feature)` Convenience method for checking whether specified serialization feature is enabled or not.
    `abstract void` | `serializeValue(SerializationConfig cfg, JsonGenerator jgen, Object value, JavaType rootType, SerializerFactory jsf)` The method to be called by `ObjectMapper` to execute recursive serialization, using serializers that this provider has access to; and using specified root type for locating first-level serializer.
    `abstract void` | `serializeValue(SerializationConfig cfg, JsonGenerator jgen, Object value, SerializerFactory jsf)` The method to be called by `ObjectMapper` to execute recursive serialization, using serializers that this provider has access to.
    `abstract void` | `setDefaultKeySerializer(JsonSerializer<Object> ks)` Method that can be used to specify serializer to use for serializing all non-null JSON property names, unless more specific key serializer is found (i.e.
    `abstract void` | `setNullKeySerializer(JsonSerializer<Object> nks)` Method that can be used to specify serializer that will be used to write JSON property names matching null keys for Java Maps (which will throw an exception if try write such property name)
    `abstract void` | `setNullValueSerializer(JsonSerializer<Object> nvs)` Method that can be used to specify serializer that will be used to write JSON values matching Java null values instead of default one (which simply writes JSON null)

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

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

- - ### Field Detail

    - #### TYPE_OBJECT

          protected static final JavaType TYPE_OBJECT

    - #### _config

          protected final SerializationConfig _config

      Serialization configuration to use for serialization processing.

    - #### _serializationView

          protected final Class<?> _serializationView

      View used for currently active serialization

  - ### Constructor Detail

    - #### SerializerProvider

          protected SerializerProvider(SerializationConfig config)

  - ### Method Detail

    - #### setNullKeySerializer

          public abstract void setNullKeySerializer(JsonSerializer<Object> nks)

      Method that can be used to specify serializer that will be used to write JSON property names matching null keys for Java Maps (which will throw an exception if try write such property name)
      Since:
        1.8

    - #### setNullValueSerializer

          public abstract void setNullValueSerializer(JsonSerializer<Object> nvs)

      Method that can be used to specify serializer that will be used to write JSON values matching Java null values instead of default one (which simply writes JSON null)
      Since:
        1.8

    - #### setDefaultKeySerializer

          public abstract void setDefaultKeySerializer(JsonSerializer<Object> ks)

      Method that can be used to specify serializer to use for serializing all non-null JSON property names, unless more specific key serializer is found (i.e. if not custom key serializer has been registered for Java type).

      Note that key serializer registration are different from value serializer registrations.

      Since:
        1.8

    - #### serializeValue

          public abstract void serializeValue(SerializationConfig cfg,
                            JsonGenerator jgen,
                            Object value,
                            SerializerFactory jsf)
                                       throws IOException,
                                              JsonGenerationException

      The method to be called by `ObjectMapper` to execute recursive serialization, using serializers that this provider has access to.
      Parameters:
        `jsf` - Underlying factory object used for creating serializers as needed
      Throws:
        `IOException`
        `JsonGenerationException`

    - #### serializeValue

          public abstract void serializeValue(SerializationConfig cfg,
                            JsonGenerator jgen,
                            Object value,
                            JavaType rootType,
                            SerializerFactory jsf)
                                       throws IOException,
                                              JsonGenerationException

      The method to be called by `ObjectMapper` to execute recursive serialization, using serializers that this provider has access to; and using specified root type for locating first-level serializer.
      Parameters:
        `rootType` - Type to use for locating serializer to use, instead of actual runtime type. Must be actual type, or one of its super types
      Throws:
        `IOException`
        `JsonGenerationException`
      Since:
        1.5

    - #### generateJsonSchema

          public abstract JsonSchema generateJsonSchema(Class<?> type,
                                      SerializationConfig config,
                                      SerializerFactory jsf)
                                                 throws JsonMappingException

      Generate Json-schema for given type.
      Parameters:
        `type` - The type for which to generate schema
      Throws:
        `JsonMappingException`

    - #### hasSerializerFor

          public abstract boolean hasSerializerFor(SerializationConfig cfg,
                                 Class<?> cls,
                                 SerializerFactory jsf)

      Method that can be called to see if this serializer provider can find a serializer for an instance of given class.

      Note that no Exceptions are thrown, including unchecked ones: implementations are to swallow exceptions if necessary.

    - #### getConfig

          public final SerializationConfig getConfig()

      Method for accessing configuration for the serialization processing.

    - #### isEnabled

          public final boolean isEnabled(SerializationConfig.Feature feature)

      Convenience method for checking whether specified serialization feature is enabled or not. Shortcut for:

            getConfig().isEnabled(feature);

    - #### getSerializationView

          public final Class<?> getSerializationView()

      Convenience method for accessing serialization view in use (if any); equivalent to:

             getConfig().getSerializationView();

      Since:
        1.4

    - #### getFilterProvider

          public final FilterProvider getFilterProvider()

      Convenience method for accessing provider to find serialization filters used, equivalent to calling:

             getConfig().getFilterProvider();

      Since:
        1.4

    - #### constructType

          public JavaType constructType(Type type)

      Since:
        1.8

    - #### constructSpecializedType

          public JavaType constructSpecializedType(JavaType baseType,
                                          Class<?> subclass)

      Since:
        1.9.1

    - #### findValueSerializer

          public abstract JsonSerializer<Object> findValueSerializer(Class<?> runtimeType,
                                                   BeanProperty property)
                                                              throws JsonMappingException

      Method called to get hold of a serializer for a value of given type; or if no such serializer can be found, a default handler (which may do a best-effort generic serialization or just simply throw an exception when invoked).

      Note: this method is only called for non-null values; not for keys or null values. For these, check out other accessor methods.

      Note that starting with version 1.5, serializers should also be type-aware if they handle polymorphic types. That means that it may be necessary to also use a `TypeSerializer` based on declared (static) type being serializer (whereas actual data may be serialized using dynamic type)

      Throws:
        `JsonMappingException` - if there are fatal problems with accessing suitable serializer; including that of not finding any serializer

    - #### findValueSerializer

          public abstract JsonSerializer<Object> findValueSerializer(JavaType serializationType,
                                                   BeanProperty property)
                                                              throws JsonMappingException

      Similar to `findValueSerializer(Class)`, but takes full generics-aware type instead of raw class.
      Throws:
        `JsonMappingException`
      Since:
        1.5

    - #### findTypedValueSerializer

          public abstract JsonSerializer<Object> findTypedValueSerializer(Class<?> valueType,
                                                        boolean cache,
                                                        BeanProperty property)
                                                                   throws JsonMappingException

      Method called to locate regular serializer, matching type serializer, and if both found, wrap them in a serializer that calls both in correct sequence. This method is currently only used for root-level serializer handling to allow for simpler caching. A call can always be replaced by equivalent calls to access serializer and type serializer separately.
      Parameters:
        `valueType` - Type for purpose of locating a serializer; usually dynamic runtime type, but can also be static declared type, depending on configuration
        `cache` - Whether resulting value serializer should be cached or not; this is just a hint
      Throws:
        `JsonMappingException`
      Since:
        1.5

    - #### findTypedValueSerializer

          public abstract JsonSerializer<Object> findTypedValueSerializer(JavaType valueType,
                                                        boolean cache,
                                                        BeanProperty property)
                                                                   throws JsonMappingException

      Method called to locate regular serializer, matching type serializer, and if both found, wrap them in a serializer that calls both in correct sequence. This method is currently only used for root-level serializer handling to allow for simpler caching. A call can always be replaced by equivalent calls to access serializer and type serializer separately.
      Parameters:
        `valueType` - Declared type of value being serialized (which may not be actual runtime type); used for finding both value serializer and type serializer to use for adding polymorphic type (if any)
        `cache` - Whether resulting value serializer should be cached or not; this is just a hint
      Throws:
        `JsonMappingException`
      Since:
        1.5

    - #### findKeySerializer

          public abstract JsonSerializer<Object> findKeySerializer(JavaType keyType,
                                                 BeanProperty property)
                                                            throws JsonMappingException

      Method called to get the serializer to use for serializing non-null Map keys. Separation from regular `findValueSerializer(java.lang.Class<?>, org.codehaus.jackson.map.BeanProperty)` method is because actual write method must be different (@link JsonGenerator#writeFieldName}; but also since behavior for some key types may differ.

      Note that the serializer itself can be called with instances of any Java object, but not nulls.

      Throws:
        `JsonMappingException`
      Since:
        1.8

    - #### findValueSerializer

          @Deprecated
          public final JsonSerializer<Object> findValueSerializer(Class<?> runtimeType)
                                                           throws JsonMappingException

      Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
      Deprecated version of accessor method that was used before version 1.7. Implemented as final to ensure that existing code does not accidentally try to redefine it (given that it is not called by core mapper code)
      Throws:
        `JsonMappingException`

    - #### findValueSerializer

          @Deprecated
          public final JsonSerializer<Object> findValueSerializer(JavaType serializationType)
                                                           throws JsonMappingException

      Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
      Deprecated version of accessor method that was used before version 1.7. Implemented as final to ensure that existing code does not accidentally try to redefine it (given that it is not called by core mapper code)
      Throws:
        `JsonMappingException`

    - #### findTypedValueSerializer

          @Deprecated
          public final JsonSerializer<Object> findTypedValueSerializer(Class<?> valueType,
                                                                   boolean cache)
                                                                throws JsonMappingException

      Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
      Deprecated version of accessor method that was used before version 1.7. Implemented as final to ensure that existing code does not accidentally try to redefine it (given that it is not called by core mapper code)
      Throws:
        `JsonMappingException`

    - #### findTypedValueSerializer

          @Deprecated
          public final JsonSerializer<Object> findTypedValueSerializer(JavaType valueType,
                                                                   boolean cache)
                                                                throws JsonMappingException

      Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
      Deprecated version of accessor method that was used before version 1.7. Implemented as final to ensure that existing code does not accidentally try to redefine it (given that it is not called by core mapper code)
      Throws:
        `JsonMappingException`

    - #### getKeySerializer

          @Deprecated
          public final JsonSerializer<Object> getKeySerializer()
                                                        throws JsonMappingException

      Deprecated. As of version 1.7, use version that exposes property object instead of just its type (needed for contextual serializers)
      Deprecated version of accessor method that was used before version 1.7. Implemented as final to ensure that existing code does not accidentally try to redefine it (given that it is not called by core mapper code)
      Throws:
        `JsonMappingException`

    - #### getKeySerializer

          @Deprecated
          public final JsonSerializer<Object> getKeySerializer(JavaType valueType,
                                                           BeanProperty property)
                                                        throws JsonMappingException

      Deprecated. As of version 1.8
      Deprecated version of accessor method that was used before version 1.8; renamed as `findKeySerializer(org.codehaus.jackson.type.JavaType, org.codehaus.jackson.map.BeanProperty)`, since process is now more complicated than simple lookup.
      Throws:
        `JsonMappingException`

    - #### getNullKeySerializer

          public abstract JsonSerializer<Object> getNullKeySerializer()

      Method called to get the serializer to use for serializing Map keys that are nulls: this is needed since JSON does not allow any non-String value as key, including null.

      Typically, returned serializer will either throw an exception, or use an empty String; but other behaviors are possible.

    - #### getNullValueSerializer

          public abstract JsonSerializer<Object> getNullValueSerializer()

      Method called to get the serializer to use for serializing values (root level, Array members or List field values) that are nulls. Specific accessor is needed because nulls in Java do not contain type information.

      Typically returned serializer just writes out Json literal null value.

    - #### getUnknownTypeSerializer

          public abstract JsonSerializer<Object> getUnknownTypeSerializer(Class<?> unknownType)

      Method called to get the serializer to use if provider can not determine an actual type-specific serializer to use; typically when none of `SerializerFactory` instances are able to construct a serializer.

      Typically, returned serializer will throw an exception, although alternatively `ToStringSerializer` could be returned as well.

      Parameters:
        `unknownType` - Type for which no serializer is found

    - #### defaultSerializeValue

          public final void defaultSerializeValue(Object value,
                                   JsonGenerator jgen)
                                           throws IOException,
                                                  JsonProcessingException

      Convenience method that will serialize given value (which can be null) using standard serializer locating functionality. It can be called for all values including field and Map values, but usually field values are best handled calling `defaultSerializeField(java.lang.String, java.lang.Object, org.codehaus.jackson.JsonGenerator)` instead.
      Throws:
        `IOException`
        `JsonProcessingException`

    - #### defaultSerializeField

          public final void defaultSerializeField(String fieldName,
                                   Object value,
                                   JsonGenerator jgen)
                                           throws IOException,
                                                  JsonProcessingException

      Convenience method that will serialize given field with specified value. Value may be null. Serializer is done using the usual null) using standard serializer locating functionality.
      Throws:
        `IOException`
        `JsonProcessingException`

    - #### defaultSerializeDateValue

          public abstract void defaultSerializeDateValue(long timestamp,
                                       JsonGenerator jgen)
                                                  throws IOException,
                                                         JsonProcessingException

      Method that will handle serialization of Date(-like) values, using `SerializationConfig` settings to determine expected serialization behavior. Note: date here means "full" date, that is, date AND time, as per Java convention (and not date-only values like in SQL)
      Throws:
        `IOException`
        `JsonProcessingException`

    - #### defaultSerializeDateValue

          public abstract void defaultSerializeDateValue(Date date,
                                       JsonGenerator jgen)
                                                  throws IOException,
                                                         JsonProcessingException

      Method that will handle serialization of Date(-like) values, using `SerializationConfig` settings to determine expected serialization behavior. Note: date here means "full" date, that is, date AND time, as per Java convention (and not date-only values like in SQL)
      Throws:
        `IOException`
        `JsonProcessingException`

    - #### defaultSerializeDateKey

          public abstract void defaultSerializeDateKey(long timestamp,
                                     JsonGenerator jgen)
                                                throws IOException,
                                                       JsonProcessingException

      Method that will handle serialization of Dates used as `Map` keys, based on `SerializationConfig.Feature.WRITE_DATE_KEYS_AS_TIMESTAMPS` value (and if using textual representation, configured date format)
      Throws:
        `IOException`
        `JsonProcessingException`
      Since:
        1.9

    - #### defaultSerializeDateKey

          public abstract void defaultSerializeDateKey(Date date,
                                     JsonGenerator jgen)
                                                throws IOException,
                                                       JsonProcessingException

      Method that will handle serialization of Dates used as `Map` keys, based on `SerializationConfig.Feature.WRITE_DATE_KEYS_AS_TIMESTAMPS` value (and if using textual representation, configured date format)
      Throws:
        `IOException`
        `JsonProcessingException`
      Since:
        1.9

    - #### defaultSerializeNull

          public final void defaultSerializeNull(JsonGenerator jgen)
                                          throws IOException,
                                                 JsonProcessingException

      Throws:
        `IOException`
        `JsonProcessingException`
      Since:
        1.7

    - #### cachedSerializersCount

          public abstract int cachedSerializersCount()

      Method that can be used to determine how many serializers this provider is caching currently (if it does caching: default implementation does) Exact count depends on what kind of serializers get cached; default implementation caches all serializers, including ones that are eagerly constructed (for optimal access speed)

      The main use case for this method is to allow conditional flushing of serializer cache, if certain number of entries is reached.

      Since:
        1.4

    - #### flushCachedSerializers

          public abstract void flushCachedSerializers()

      Method that will drop all serializers currently cached by this provider. This can be used to remove memory usage (in case some serializers are only used once or so), or to force re-construction of serializers after configuration changes for mapper than owns the provider.
      Since:
        1.4