org.codehaus.jackson.map.ser
Class StdSerializerProvider

java.lang.Object
  extended by org.codehaus.jackson.map.SerializerProvider
      extended by org.codehaus.jackson.map.ser.StdSerializerProvider

public class StdSerializerProvider
extends SerializerProvider

Default SerializerProvider implementation. Handles caching aspects of serializer handling; all construction details are delegated to SerializerFactory instance.

One note about implementation: the main instance constructed will be so-called "blueprint" object, and will NOT be used during actual serialization. Rather, an "instance" instance is created so that state can be carried along, as well as to avoid synchronization during serializer access. Because of this, if sub-classing, one must override method createInstance(org.codehaus.jackson.map.SerializationConfig, org.codehaus.jackson.map.SerializerFactory): if this is not done, an exception will get thrown as base class verifies that the instance has same class as the blueprint (instance.getClass() == blueprint.getClass()). Check is done to prevent weird bugs that would otherwise occur.

Starting with version 1.5, provider is also responsible for some parts of type serialization; specifically for locating proper type serializers to use for types.


Field Summary
protected  DateFormat _dateFormat
          Lazily acquired and instantiated formatter object: initialized first time it is needed, reused afterwards.
protected  JsonSerializer<Object> _keySerializer
          Serializer used to output non-null keys of Maps (which will get output as Json Objects).
protected  ReadOnlyClassToSerializerMap _knownSerializers
          For fast lookups, we will have a local non-shared read-only map that contains serializers previously fetched.
protected  JsonSerializer<Object> _nullKeySerializer
          Serializer used to (try to) output a null key, due to an entry of Map having null key.
protected  JsonSerializer<Object> _nullValueSerializer
          Serializer used to output a null value.
protected  RootNameLookup _rootNames
           
protected  SerializerCache _serializerCache
           
protected  SerializerFactory _serializerFactory
           
protected  JsonSerializer<Object> _unknownTypeSerializer
          Serializer that gets called for values of types for which no serializers can be constructed.
static JsonSerializer<Object> DEFAULT_KEY_SERIALIZER
           
static JsonSerializer<Object> DEFAULT_NULL_KEY_SERIALIZER
           
static JsonSerializer<Object> DEFAULT_UNKNOWN_SERIALIZER
           
 
Fields inherited from class org.codehaus.jackson.map.SerializerProvider
_config, _serializationView, TYPE_OBJECT
 
Constructor Summary
  StdSerializerProvider()
          Constructor for creating master (or "blue-print") provider object, which is only used as the template for constructing per-binding instances.
protected StdSerializerProvider(SerializationConfig config, StdSerializerProvider src, SerializerFactory f)
          "Copy-constructor", used from createInstance(org.codehaus.jackson.map.SerializationConfig, org.codehaus.jackson.map.SerializerFactory) (or by sub-classes)
 
Method Summary
protected  JsonSerializer<Object> _createAndCacheUntypedSerializer(Class<?> type, BeanProperty property)
          Method that will try to construct a value serializer; and if one is succesfully created, cache it for reuse.
protected  JsonSerializer<Object> _createAndCacheUntypedSerializer(JavaType type, BeanProperty property)
           
protected  JsonSerializer<Object> _createUntypedSerializer(JavaType type, BeanProperty property)
           
protected  JsonSerializer<Object> _findExplicitUntypedSerializer(Class<?> runtimeType, BeanProperty property)
          Method that will try to find a serializer, either from cache or by constructing one; but will not return an "unknown" serializer if this can not be done but rather returns null.
protected  void _reportIncompatibleRootType(Object value, JavaType rootType)
           
protected  void _resolveSerializer(ResolvableSerializer ser)
           
protected  void _serializeValue(JsonGenerator jgen, Object value)
          Method called on the actual non-blueprint provider instance object, to kick off the serialization.
protected  void _serializeValue(JsonGenerator jgen, Object value, JavaType rootType)
          Method called on the actual non-blueprint provider instance object, to kick off the serialization, when root type is explicitly specified and not determined from value.
 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)
protected  StdSerializerProvider createInstance(SerializationConfig config, SerializerFactory jsf)
          Overridable method, used to create a non-blueprint instances from the blueprint.
 void defaultSerializeDateValue(Date date, JsonGenerator jgen)
          Method that will handle serialization of Date(-like) values, using SerializationConfig settings to determine expected serialization behavior.
 void defaultSerializeDateValue(long timestamp, JsonGenerator jgen)
          Method that will handle serialization of Date(-like) values, using SerializationConfig settings to determine expected serialization behavior.
 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, 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<?> valueType, 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 valueType, BeanProperty property)
          This variant was added in 1.5, to allow for efficient access using full structured types, not just classes.
 void flushCachedSerializers()
          Method that will drop all serializers currently cached by this provider.
 JsonSchema generateJsonSchema(Class<?> type, SerializationConfig config, SerializerFactory jsf)
          Generate Json-schema for given type.
 JsonSerializer<Object> getKeySerializer(JavaType valueType, BeanProperty property)
          Method called to get the serializer to use for serializing non-null Map keys.
 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.
 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.
 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.
 boolean hasSerializerFor(SerializationConfig config, 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.
 void serializeValue(SerializationConfig config, 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.
 void serializeValue(SerializationConfig config, 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.
 void setKeySerializer(JsonSerializer<Object> ks)
           
 void setNullKeySerializer(JsonSerializer<Object> nks)
           
 void setNullValueSerializer(JsonSerializer<Object> nvs)
           
 
Methods inherited from class org.codehaus.jackson.map.SerializerProvider
defaultSerializeField, defaultSerializeNull, defaultSerializeValue, findTypedValueSerializer, findTypedValueSerializer, findValueSerializer, findValueSerializer, getConfig, getFilterProvider, getKeySerializer, getSerializationView, isEnabled
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_NULL_KEY_SERIALIZER

public static final JsonSerializer<Object> DEFAULT_NULL_KEY_SERIALIZER

DEFAULT_KEY_SERIALIZER

public static final JsonSerializer<Object> DEFAULT_KEY_SERIALIZER

DEFAULT_UNKNOWN_SERIALIZER

public static final JsonSerializer<Object> DEFAULT_UNKNOWN_SERIALIZER

_serializerFactory

protected final SerializerFactory _serializerFactory

_serializerCache

protected final SerializerCache _serializerCache

_rootNames

protected final RootNameLookup _rootNames

_unknownTypeSerializer

protected JsonSerializer<Object> _unknownTypeSerializer
Serializer that gets called for values of types for which no serializers can be constructed.

The default serializer will simply thrown an exception; a possible alternative that can be used would be ToStringSerializer.


_keySerializer

protected JsonSerializer<Object> _keySerializer
Serializer used to output non-null keys of Maps (which will get output as Json Objects).


_nullValueSerializer

protected JsonSerializer<Object> _nullValueSerializer
Serializer used to output a null value. Default implementation writes nulls using JsonGenerator.writeNull().


_nullKeySerializer

protected JsonSerializer<Object> _nullKeySerializer
Serializer used to (try to) output a null key, due to an entry of Map having null key. The default implementation will throw an exception if this happens; alternative implementation (like one that would write an Empty String) can be defined.


_knownSerializers

protected final ReadOnlyClassToSerializerMap _knownSerializers
For fast lookups, we will have a local non-shared read-only map that contains serializers previously fetched.


_dateFormat

protected DateFormat _dateFormat
Lazily acquired and instantiated formatter object: initialized first time it is needed, reused afterwards. Used via instances (not blueprints), so that access need not be thread-safe.

Constructor Detail

StdSerializerProvider

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


StdSerializerProvider

protected StdSerializerProvider(SerializationConfig config,
                                StdSerializerProvider src,
                                SerializerFactory f)
"Copy-constructor", used from createInstance(org.codehaus.jackson.map.SerializationConfig, org.codehaus.jackson.map.SerializerFactory) (or by sub-classes)

Parameters:
src - Blueprint object used as the baseline for this instance
Method Detail

createInstance

protected StdSerializerProvider createInstance(SerializationConfig config,
                                               SerializerFactory jsf)
Overridable method, used to create a non-blueprint instances from the blueprint. This is needed to retain state during serialization.


serializeValue

public final void serializeValue(SerializationConfig config,
                                 JsonGenerator jgen,
                                 Object value,
                                 SerializerFactory jsf)
                          throws IOException,
                                 JsonGenerationException
Description copied from class: SerializerProvider
The method to be called by ObjectMapper to execute recursive serialization, using serializers that this provider has access to.

Specified by:
serializeValue in class SerializerProvider
jsf - Underlying factory object used for creating serializers as needed
Throws:
IOException
JsonGenerationException

serializeValue

public final void serializeValue(SerializationConfig config,
                                 JsonGenerator jgen,
                                 Object value,
                                 JavaType rootType,
                                 SerializerFactory jsf)
                          throws IOException,
                                 JsonGenerationException
Description copied from class: SerializerProvider
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.

Specified by:
serializeValue in class SerializerProvider
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

generateJsonSchema

public JsonSchema generateJsonSchema(Class<?> type,
                                     SerializationConfig config,
                                     SerializerFactory jsf)
                              throws JsonMappingException
Description copied from class: SerializerProvider
Generate Json-schema for given type.

Specified by:
generateJsonSchema in class SerializerProvider
Parameters:
type - The type for which to generate schema
Throws:
JsonMappingException

hasSerializerFor

public boolean hasSerializerFor(SerializationConfig config,
                                Class<?> cls,
                                SerializerFactory jsf)
Description copied from class: SerializerProvider
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.

Specified by:
hasSerializerFor in class SerializerProvider

setKeySerializer

public void setKeySerializer(JsonSerializer<Object> ks)

setNullValueSerializer

public void setNullValueSerializer(JsonSerializer<Object> nvs)

setNullKeySerializer

public void setNullKeySerializer(JsonSerializer<Object> nks)

cachedSerializersCount

public int cachedSerializersCount()
Description copied from class: SerializerProvider
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.

Specified by:
cachedSerializersCount in class SerializerProvider

flushCachedSerializers

public void flushCachedSerializers()
Description copied from class: SerializerProvider
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.

Specified by:
flushCachedSerializers in class SerializerProvider

findValueSerializer

public JsonSerializer<Object> findValueSerializer(Class<?> valueType,
                                                  BeanProperty property)
                                           throws JsonMappingException
Description copied from class: SerializerProvider
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)

Specified by:
findValueSerializer in class SerializerProvider
Throws:
JsonMappingException - if there are fatal problems with accessing suitable serializer; including that of not finding any serializer

findValueSerializer

public JsonSerializer<Object> findValueSerializer(JavaType valueType,
                                                  BeanProperty property)
                                           throws JsonMappingException
This variant was added in 1.5, to allow for efficient access using full structured types, not just classes. This is necessary for accurate handling of external type information, to handle polymorphic types.

Specified by:
findValueSerializer in class SerializerProvider
Throws:
JsonMappingException

findTypedValueSerializer

public JsonSerializer<Object> findTypedValueSerializer(Class<?> valueType,
                                                       boolean cache,
                                                       BeanProperty property)
                                                throws JsonMappingException
Description copied from class: SerializerProvider
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.

Specified by:
findTypedValueSerializer in class SerializerProvider
Parameters:
cache - Whether resulting value serializer should be cached or not; this is just a hint
valueType - Type for purpose of locating a serializer; usually dynamic runtime type, but can also be static declared type, depending on configuration
Throws:
JsonMappingException

findTypedValueSerializer

public JsonSerializer<Object> findTypedValueSerializer(JavaType valueType,
                                                       boolean cache,
                                                       BeanProperty property)
                                                throws JsonMappingException
Description copied from class: SerializerProvider
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.

Specified by:
findTypedValueSerializer in class SerializerProvider
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

getKeySerializer

public JsonSerializer<Object> getKeySerializer(JavaType valueType,
                                               BeanProperty property)
Description copied from class: SerializerProvider
Method called to get the serializer to use for serializing non-null Map keys. Separation from regular SerializerProvider.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.

Specified by:
getKeySerializer in class SerializerProvider

getNullKeySerializer

public JsonSerializer<Object> getNullKeySerializer()
Description copied from class: SerializerProvider
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.

Specified by:
getNullKeySerializer in class SerializerProvider

getNullValueSerializer

public JsonSerializer<Object> getNullValueSerializer()
Description copied from class: SerializerProvider
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.

Specified by:
getNullValueSerializer in class SerializerProvider

getUnknownTypeSerializer

public JsonSerializer<Object> getUnknownTypeSerializer(Class<?> unknownType)
Description copied from class: SerializerProvider
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.

Specified by:
getUnknownTypeSerializer in class SerializerProvider
Parameters:
unknownType - Type for which no serializer is found

defaultSerializeDateValue

public final void defaultSerializeDateValue(long timestamp,
                                            JsonGenerator jgen)
                                     throws IOException,
                                            JsonProcessingException
Description copied from class: SerializerProvider
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)

Specified by:
defaultSerializeDateValue in class SerializerProvider
Parameters:
timestamp - Millisecond timestamp that defines date, if available;
Throws:
IOException
JsonProcessingException

defaultSerializeDateValue

public final void defaultSerializeDateValue(Date date,
                                            JsonGenerator jgen)
                                     throws IOException,
                                            JsonProcessingException
Description copied from class: SerializerProvider
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)

Specified by:
defaultSerializeDateValue in class SerializerProvider
Throws:
IOException
JsonProcessingException

_serializeValue

protected void _serializeValue(JsonGenerator jgen,
                               Object value)
                        throws IOException,
                               JsonProcessingException
Method called on the actual non-blueprint provider instance object, to kick off the serialization.

Throws:
IOException
JsonProcessingException

_serializeValue

protected void _serializeValue(JsonGenerator jgen,
                               Object value,
                               JavaType rootType)
                        throws IOException,
                               JsonProcessingException
Method called on the actual non-blueprint provider instance object, to kick off the serialization, when root type is explicitly specified and not determined from value.

Throws:
IOException
JsonProcessingException

_reportIncompatibleRootType

protected void _reportIncompatibleRootType(Object value,
                                           JavaType rootType)
                                    throws IOException,
                                           JsonProcessingException
Throws:
IOException
JsonProcessingException

_findExplicitUntypedSerializer

protected JsonSerializer<Object> _findExplicitUntypedSerializer(Class<?> runtimeType,
                                                                BeanProperty property)
Method that will try to find a serializer, either from cache or by constructing one; but will not return an "unknown" serializer if this can not be done but rather returns null.

Returns:
Serializer if one can be found, null if not.

_createAndCacheUntypedSerializer

protected JsonSerializer<Object> _createAndCacheUntypedSerializer(Class<?> type,
                                                                  BeanProperty property)
                                                           throws JsonMappingException
Method that will try to construct a value serializer; and if one is succesfully created, cache it for reuse.

Throws:
JsonMappingException

_createAndCacheUntypedSerializer

protected JsonSerializer<Object> _createAndCacheUntypedSerializer(JavaType type,
                                                                  BeanProperty property)
                                                           throws JsonMappingException
Throws:
JsonMappingException
Since:
1.5 ]

_createUntypedSerializer

protected JsonSerializer<Object> _createUntypedSerializer(JavaType type,
                                                          BeanProperty property)
                                                   throws JsonMappingException
Throws:
JsonMappingException

_resolveSerializer

protected void _resolveSerializer(ResolvableSerializer ser)
                           throws JsonMappingException
Throws:
JsonMappingException