Package com.fasterxml.jackson.databind

Class SerializerProvider

  • Direct Known Subclasses:
    DefaultSerializerProvider
    public abstract class SerializerProvider
extends DatabindContext
    Class that defines API used by ObjectMapper and JsonSerializers to obtain serializers capable of serializing instances of specific types; as well as the default implementation of the functionality.

    Provider handles caching aspects of serializer handling; all construction details are delegated to SerializerFactory instance.

    Object life-cycle is such that an initial instance ("blueprint") is created and referenced by ObjectMapper and ObjectWriter intances; but for actual usage, a configured instance is created by using a create method in sub-class DefaultSerializerProvider. Only this instance can be used for actual serialization calls; blueprint object is only to be used for creating instances.

    • Field Detail

      • DEFAULT_NULL_KEY_SERIALIZER

        public static final JsonSerializer<java.lang.Object> DEFAULT_NULL_KEY_SERIALIZER

    • Constructor Detail

      • SerializerProvider

        public SerializerProvider()
        Constructor for creating master (or "blue-print") provider object, which is only used as the template for constructing per-binding instances.

    • Method Detail

      • setDefaultKeySerializer

        public void setDefaultKeySerializer​(JsonSerializer<java.lang.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.

      • setNullValueSerializer

        public void setNullValueSerializer​(JsonSerializer<java.lang.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).

        Note that you can get finer control over serializer to use by overriding findNullValueSerializer(com.fasterxml.jackson.databind.BeanProperty), which gets called once per each property.

      • setNullKeySerializer

        public void setNullKeySerializer​(JsonSerializer<java.lang.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 otherwise throw an exception if try write such property name)

      • constructSpecializedType

        public JavaType constructSpecializedType​(JavaType baseType,
                                         java.lang.Class<?> subclass)
                                  throws java.lang.IllegalArgumentException
        Description copied from class: DatabindContext
        Convenience method for constructing subtypes, retaining generic type parameter (if any).

        Note: since 2.11 handling has varied a bit across serialization, deserialization.

        Specified by:
        constructSpecializedType in class DatabindContext
        Throws:
        java.lang.IllegalArgumentException

      • getActiveView

        public final java.lang.Class<?> getActiveView()
        Description copied from class: DatabindContext
        Accessor for locating currently active view, if any; returns null if no view has been set.
        Specified by:
        getActiveView in class DatabindContext

      • canOverrideAccessModifiers

        public final boolean canOverrideAccessModifiers()
        Description copied from class: DatabindContext
        Convenience method for accessing serialization view in use (if any); equivalent to: 
           getConfig().canOverrideAccessModifiers();
        Specified by:
        canOverrideAccessModifiers in class DatabindContext

      • isEnabled

        public final boolean isEnabled​(MapperFeature feature)
        Description copied from class: DatabindContext
        Convenience method for checking whether specified serialization feature is enabled or not. Shortcut for: 
          getConfig().isEnabled(feature);
        Specified by:
        isEnabled in class DatabindContext

      • getDefaultPropertyInclusion

        public final JsonInclude.Value getDefaultPropertyInclusion​(java.lang.Class<?> baseType)
        Since:
        2.8

      • getLocale

        public java.util.Locale getLocale()
        Method for accessing default Locale to use: convenience method for 
           getConfig().getLocale();
        Specified by:
        getLocale in class DatabindContext

      • getTimeZone

        public java.util.TimeZone getTimeZone()
        Method for accessing default TimeZone to use: convenience method for 
           getConfig().getTimeZone();
        Specified by:
        getTimeZone in class DatabindContext

      • getAttribute

        public java.lang.Object getAttribute​(java.lang.Object key)
        Description copied from class: DatabindContext
        Method for accessing attributes available in this context. Per-call attributes have highest precedence; attributes set via ObjectReader or ObjectWriter have lower precedence.
        Specified by:
        getAttribute in class DatabindContext
        Parameters:
        key - Key of the attribute to get
        Returns:
        Value of the attribute, if any; null otherwise

      • setAttribute

        public SerializerProvider setAttribute​(java.lang.Object key,
                                       java.lang.Object value)
        Description copied from class: DatabindContext
        Method for setting per-call value of given attribute. This will override any previously defined value for the attribute within this context.
        Specified by:
        setAttribute in class DatabindContext
        Parameters:
        key - Key of the attribute to set
        value - Value to set attribute to
        Returns:
        This context object, to allow chaining

      • isEnabled

        public final boolean isEnabled​(SerializationFeature feature)
        Convenience method for checking whether specified serialization feature is enabled or not. Shortcut for: 
          getConfig().isEnabled(feature);

      • hasSerializationFeatures

        public final boolean hasSerializationFeatures​(int featureMask)
        "Bulk" access method for checking that all features specified by mask are enabled.
        Since:
        2.3

      • getFilterProvider

        public final FilterProvider getFilterProvider()
        Convenience method for accessing provider to find serialization filters used, equivalent to calling: 
           getConfig().getFilterProvider();

      • getGenerator

        public JsonGenerator getGenerator()

        NOTE: current implementation simply returns `null` as generator is not yet assigned to this provider.

        Since:
        2.8

      • bufferForValueConversion

        public TokenBuffer bufferForValueConversion​(ObjectCodec oc)
        Specialized factory method used when we are converting values and do not typically have or use "real" parsers or generators.
        Since:
        2.13

      • bufferForValueConversion

        public final TokenBuffer bufferForValueConversion()
        Specialized factory method used when we are converting values and do not typically have or use "real" parsers or generators.
        Since:
        2.13

      • findObjectId

        public abstract WritableObjectId findObjectId​(java.lang.Object forPojo,
                                              ObjectIdGenerator<?> generatorType)
        Method called to find the Object Id for given POJO, if one has been generated. Will always return a non-null Object; contents vary depending on whether an Object Id already exists or not.

      • findValueSerializer

        public JsonSerializer<java.lang.Object> findValueSerializer​(java.lang.Class<?> valueType,
                                                            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 serializers produced should NOT handle polymorphic serialization aspects; separate TypeSerializer is to be constructed by caller if and as necessary.

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

      • findValueSerializer

        public JsonSerializer<java.lang.Object> findValueSerializer​(JavaType valueType,
                                                            BeanProperty property)
                                                     throws JsonMappingException
        Similar to findValueSerializer(Class,BeanProperty), but takes full generics-aware type instead of raw class. This is necessary for accurate handling of external type information, to handle polymorphic types.

        Note: this call will also contextualize serializer before returning it.

        Parameters:
        property - When creating secondary serializers, property for which serializer is needed: annotations of the property (or bean that contains it) may be checked to create contextual serializers.
        Throws:
        JsonMappingException

      • findValueSerializer

        public JsonSerializer<java.lang.Object> findValueSerializer​(java.lang.Class<?> valueType)
                                                     throws JsonMappingException
        Method variant used when we do NOT want contextualization to happen; it will need to be handled at a later point, but caller wants to be able to do that as needed; sometimes to avoid infinite loops
        Throws:
        JsonMappingException
        Since:
        2.5

      • findValueSerializer

        public JsonSerializer<java.lang.Object> findValueSerializer​(JavaType valueType)
                                                     throws JsonMappingException
        Method variant used when we do NOT want contextualization to happen; it will need to be handled at a later point, but caller wants to be able to do that as needed; sometimes to avoid infinite loops
        Throws:
        JsonMappingException
        Since:
        2.5

      • findPrimaryPropertySerializer

        public JsonSerializer<java.lang.Object> findPrimaryPropertySerializer​(JavaType valueType,
                                                                      BeanProperty property)
                                                               throws JsonMappingException
        Similar to findValueSerializer(JavaType, BeanProperty), but used when finding "primary" property value serializer (one directly handling value of the property). Difference has to do with contextual resolution, and method(s) called: this method should only be called when caller is certain that this is the primary property value serializer.
        Parameters:
        valueType - Type of values to serialize
        property - Property that is being handled; will never be null, and its type has to match valueType parameter.
        Throws:
        JsonMappingException
        Since:
        2.3

      • findContentValueSerializer

        public JsonSerializer<java.lang.Object> findContentValueSerializer​(JavaType valueType,
                                                                   BeanProperty property)
                                                            throws JsonMappingException
        Alternative to findPrimaryPropertySerializer(JavaType, BeanProperty) called not for primary value, but "content" of such primary serializer: element of an array or Collection, value of Map entry and so on. This means that property passed (if any) does NOT represent value for which serializer is requested but its secondary type (or secondary type of that type, recursively).

        Serializer returned SHOULD NOT handle type information; caller will (have to) add suitable wrapping if necessary.

        Note: this call will also contextualize serializer (call createContextual() before returning it, if applicable (implements ContextualSerializer)

        Parameters:
        valueType - Type of values to serialize
        property - Property that indirectly refers to value being serialized (optional, may be null for root level serializers)
        Throws:
        JsonMappingException
        Since:
        2.11

      • findTypedValueSerializer

        public JsonSerializer<java.lang.Object> findTypedValueSerializer​(java.lang.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
        property - When creating secondary serializers, property for which serializer is needed: annotations of the property (or bean that contains it) may be checked to create contextual serializers.
        Throws:
        JsonMappingException

      • findTypedValueSerializer

        public JsonSerializer<java.lang.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
        property - When creating secondary serializers, property for which serializer is needed: annotations of the property (or bean that contains it) may be checked to create contextual serializers.
        Throws:
        JsonMappingException

      • getDefaultNullKeySerializer

        public JsonSerializer<java.lang.Object> getDefaultNullKeySerializer()
        Since:
        2.0

      • getDefaultNullValueSerializer

        public JsonSerializer<java.lang.Object> getDefaultNullValueSerializer()
        Since:
        2.0

      • findNullKeySerializer

        public JsonSerializer<java.lang.Object> findNullKeySerializer​(JavaType serializationType,
                                                              BeanProperty property)
                                                       throws JsonMappingException
        Method called to find a serializer to use for null values for given declared type. Note that type is completely based on declared type, since nulls in Java have no type and thus runtime type cannot be determined.
        Throws:
        JsonMappingException
        Since:
        2.0

      • findNullValueSerializer

        public JsonSerializer<java.lang.Object> findNullValueSerializer​(BeanProperty property)
                                                         throws JsonMappingException
        Method called to get the serializer to use for serializing null values for specified property.

        Default implementation simply calls getDefaultNullValueSerializer(); can be overridden to add custom null serialization for properties of certain type or name. This gives method full granularity to basically override null handling for any specific property or class of properties.

        Throws:
        JsonMappingException
        Since:
        2.0

      • getUnknownTypeSerializer

        public JsonSerializer<java.lang.Object> getUnknownTypeSerializer​(java.lang.Class<?> unknownType)
        Method called to get the serializer to use if provider cannot 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

      • isUnknownTypeSerializer

        public boolean isUnknownTypeSerializer​(JsonSerializer<?> ser)
        Helper method called to see if given serializer is considered to be something returned by getUnknownTypeSerializer(java.lang.Class<?>), that is, something for which no regular serializer was found or constructed.
        Since:
        2.5

      • serializerInstance

        public abstract JsonSerializer<java.lang.Object> serializerInstance​(Annotated annotated,
                                                                    java.lang.Object serDef)
                                                             throws JsonMappingException
        Method that can be called to construct and configure serializer instance, either given a Class to instantiate (with default constructor), or an uninitialized serializer instance. Either way, serialize will be properly resolved (via ResolvableSerializer) and/or contextualized (via ContextualSerializer) as necessary.
        Parameters:
        annotated - Annotated entity that contained definition
        serDef - Serializer definition: either an instance or class
        Throws:
        JsonMappingException

      • includeFilterInstance

        public abstract java.lang.Object includeFilterInstance​(BeanPropertyDefinition forProperty,
                                                       java.lang.Class<?> filterClass)
                                                throws JsonMappingException
        Method that can be called to construct and configure JsonInclude filter instance, given a Class to instantiate (with default constructor, by default).
        Parameters:
        forProperty - (optional) If filter is created for a property, that property; `null` if filter created via defaulting, global or per-type.
        Throws:
        JsonMappingException
        Since:
        2.9

      • handleSecondaryContextualization

        public JsonSerializer<?> handleSecondaryContextualization​(JsonSerializer<?> ser,
                                                          BeanProperty property)
                                                   throws JsonMappingException
        Method called for secondary property serializers (ones NOT directly created to serialize values of a POJO property but instead created as a dependant serializer -- such as value serializers for structured types, or serializers for root values) to handle details of resolving ContextualDeserializer with given property context. Given that these serializers are not directly related to given property (or, in case of root value property, to any property), annotations accessible may or may not be relevant.
        Parameters:
        property - Property for which serializer is used, if any; null when deserializing root values
        Throws:
        JsonMappingException
        Since:
        2.3

      • defaultSerializeField

        public final void defaultSerializeField​(java.lang.String fieldName,
                                        java.lang.Object value,
                                        JsonGenerator gen)
                                 throws java.io.IOException
        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:
        java.io.IOException

      • defaultSerializeDateValue

        public final void defaultSerializeDateValue​(long timestamp,
                                            JsonGenerator gen)
                                     throws java.io.IOException
        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:
        java.io.IOException

      • defaultSerializeDateValue

        public final void defaultSerializeDateValue​(java.util.Date date,
                                            JsonGenerator gen)
                                     throws java.io.IOException
        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:
        java.io.IOException

      • defaultSerializeDateKey

        public void defaultSerializeDateKey​(long timestamp,
                                    JsonGenerator gen)
                             throws java.io.IOException
        Method that will handle serialization of Dates used as Map keys, based on SerializationFeature.WRITE_DATE_KEYS_AS_TIMESTAMPS value (and if using textual representation, configured date format)
        Throws:
        java.io.IOException

      • defaultSerializeDateKey

        public void defaultSerializeDateKey​(java.util.Date date,
                                    JsonGenerator gen)
                             throws java.io.IOException
        Method that will handle serialization of Dates used as Map keys, based on SerializationFeature.WRITE_DATE_KEYS_AS_TIMESTAMPS value (and if using textual representation, configured date format)
        Throws:
        java.io.IOException

      • defaultSerializeNull

        public final void defaultSerializeNull​(JsonGenerator gen)
                                throws java.io.IOException
        Throws:
        java.io.IOException

      • reportMappingProblem

        public void reportMappingProblem​(java.lang.String message,
                                 java.lang.Object... args)
                          throws JsonMappingException
        Helper method called to indicate problem; default behavior is to construct and throw a JsonMappingException, but in future may collect more than one and only throw after certain number, or at the end of serialization.
        Throws:
        JsonMappingException
        Since:
        2.8

      • reportBadTypeDefinition

        public <T> T reportBadTypeDefinition​(BeanDescription bean,
                                     java.lang.String msg,
                                     java.lang.Object... msgArgs)
                              throws JsonMappingException
        Helper method called to indicate problem in POJO (serialization) definitions or settings regarding specific Java type, unrelated to actual JSON content to map. Default behavior is to construct and throw a JsonMappingException.
        Throws:
        JsonMappingException
        Since:
        2.9

      • reportBadPropertyDefinition

        public <T> T reportBadPropertyDefinition​(BeanDescription bean,
                                         BeanPropertyDefinition prop,
                                         java.lang.String message,
                                         java.lang.Object... msgArgs)
                                  throws JsonMappingException
        Helper method called to indicate problem in POJO (serialization) definitions or settings regarding specific property (of a type), unrelated to actual JSON content to map. Default behavior is to construct and throw a JsonMappingException.
        Throws:
        JsonMappingException
        Since:
        2.9

      • reportBadDefinition

        public <T> T reportBadDefinition​(java.lang.Class<?> raw,
                                 java.lang.String msg,
                                 java.lang.Throwable cause)
                          throws JsonMappingException
        Throws:
        JsonMappingException
        Since:
        2.9

      • reportMappingProblem

        public void reportMappingProblem​(java.lang.Throwable t,
                                 java.lang.String message,
                                 java.lang.Object... msgArgs)
                          throws JsonMappingException
        Helper method called to indicate problem; default behavior is to construct and throw a JsonMappingException, but in future may collect more than one and only throw after certain number, or at the end of serialization.
        Throws:
        JsonMappingException
        Since:
        2.8

      • invalidTypeIdException

        public JsonMappingException invalidTypeIdException​(JavaType baseType,
                                                   java.lang.String typeId,
                                                   java.lang.String extraDesc)