Package com.fasterxml.jackson.databind

Class ObjectWriter

  • All Implemented Interfaces:
    Versioned, java.io.Serializable
    public class ObjectWriter
extends java.lang.Object
implements Versioned, java.io.Serializable
    Builder object that can be used for per-serialization configuration of serialization parameters, such as JSON View and root type to use. (and thus fully thread-safe with no external synchronization); new instances are constructed for different configurations. Instances are initially constructed by ObjectMapper and can be reused in completely thread-safe manner with no explicit synchronization
    See Also:
    Serialized Form

    • Method Detail

      • version

        public Version version()
        Method that will return version information stored in and read from jar that contains this class.
        Specified by:
        version in interface Versioned
        Returns:
        Version of the component

      • withFeatures

        public ObjectWriter withFeatures​(SerializationFeature... features)
        Method for constructing a new instance that is configured with specified features enabled.

      • without

        public ObjectWriter without​(SerializationFeature feature)
        Method for constructing a new instance that is configured with specified feature disabled.

      • withoutFeatures

        public ObjectWriter withoutFeatures​(SerializationFeature... features)
        Method for constructing a new instance that is configured with specified features disabled.

      • with

        public ObjectWriter with​(DatatypeFeature feature)
        Method for constructing a new instance that is configured with specified feature enabled.
        Since:
        2.14

      • withFeatures

        public ObjectWriter withFeatures​(DatatypeFeature... features)
        Method for constructing a new instance that is configured with specified features enabled.
        Since:
        2.14

      • without

        public ObjectWriter without​(DatatypeFeature feature)
        Method for constructing a new instance that is configured with specified feature disabled.
        Since:
        2.14

      • withoutFeatures

        public ObjectWriter withoutFeatures​(DatatypeFeature... features)
        Method for constructing a new instance that is configured with specified features disabled.
        Since:
        2.14

      • forType

        public ObjectWriter forType​(JavaType rootType)
        Method that will construct a new instance that uses specific type as the root type for serialization, instead of runtime dynamic type of the root object itself.

        Note that method does NOT change state of this reader, but rather construct and returns a newly configured instance.

        Since:
        2.5

      • forType

        public ObjectWriter forType​(java.lang.Class<?> rootType)
        Method that will construct a new instance that uses specific type as the root type for serialization, instead of runtime dynamic type of the root object itself.
        Since:
        2.5

      • forType

        public ObjectWriter forType​(TypeReference<?> rootType)
        Method that will construct a new instance that uses specific type as the root type for serialization, instead of runtime dynamic type of the root object itself.
        Since:
        2.5

      • withType

        @Deprecated
public ObjectWriter withType​(java.lang.Class<?> rootType)
        Deprecated.
        since 2.5 Use forType(Class) instead

      • with

        public ObjectWriter with​(java.text.DateFormat df)
        Fluent factory method that will construct a new writer instance that will use specified date format for serializing dates; or if null passed, one that will serialize dates as numeric timestamps.

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withDefaultPrettyPrinter

        public ObjectWriter withDefaultPrettyPrinter()
        Method that will construct a new instance that will use the default pretty printer for serialization.

      • with

        public ObjectWriter with​(FilterProvider filterProvider)
        Method that will construct a new instance that uses specified provider for resolving filter instances by id.

      • with

        public ObjectWriter with​(PrettyPrinter pp)
        Method that will construct a new instance that will use specified pretty printer (or, if null, will not do any pretty-printing)

      • withRootName

        public ObjectWriter withRootName​(java.lang.String rootName)
        Method for constructing a new instance with configuration that specifies what root name to use for "root element wrapping". See MapperConfigBase.withRootName(String) for details.

        Note that method does NOT change state of this reader, but rather construct and returns a newly configured instance.

        Parameters:
        rootName - Root name to use, if non-empty; `null` for "use defaults", and empty String ("") for "do NOT add root wrapper"

      • withoutRootName

        public ObjectWriter withoutRootName()
        Convenience method that is same as calling: withRootName("") which will forcibly prevent use of root name wrapping when writing values with this ObjectWriter.
        Since:
        2.6

      • with

        public ObjectWriter with​(FormatSchema schema)
        Method that will construct a new instance that uses specific format schema for serialization.

        Note that method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • withView

        public ObjectWriter withView​(java.lang.Class<?> view)
        Method that will construct a new instance that uses specified serialization view for serialization (with null basically disables view processing)

        Note that the method does NOT change state of this reader, but rather construct and returns a newly configured instance.

      • with

        public ObjectWriter with​(java.util.TimeZone tz)

      • withAttributes

        public ObjectWriter withAttributes​(java.util.Map<?,​?> attrs)
        Mutant factory method that allows construction of a new writer instance that uses specified set of default attribute values.
        Since:
        2.3

      • withAttribute

        public ObjectWriter withAttribute​(java.lang.Object key,
                                  java.lang.Object value)
        Since:
        2.3

      • withoutAttribute

        public ObjectWriter withoutAttribute​(java.lang.Object key)
        Since:
        2.3

      • withRootValueSeparator

        public ObjectWriter withRootValueSeparator​(java.lang.String sep)
        Since:
        2.5

      • createGenerator

        public JsonGenerator createGenerator​(java.io.OutputStream out)
                              throws java.io.IOException
        Factory method for constructing properly initialized JsonGenerator to write content using specified OutputStream. Generator is not managed (or "owned") by ObjectWriter: caller is responsible for properly closing it once content generation is complete.
        Throws:
        java.io.IOException
        Since:
        2.11

      • createGenerator

        public JsonGenerator createGenerator​(java.io.OutputStream out,
                                     JsonEncoding enc)
                              throws java.io.IOException
        Factory method for constructing properly initialized JsonGenerator to write content using specified OutputStream and encoding. Generator is not managed (or "owned") by ObjectWriter: caller is responsible for properly closing it once content generation is complete.
        Throws:
        java.io.IOException
        Since:
        2.11

      • createGenerator

        public JsonGenerator createGenerator​(java.io.Writer w)
                              throws java.io.IOException
        Factory method for constructing properly initialized JsonGenerator to write content using specified Writer. Generator is not managed (or "owned") by ObjectWriter: caller is responsible for properly closing it once content generation is complete.
        Throws:
        java.io.IOException
        Since:
        2.11

      • createGenerator

        public JsonGenerator createGenerator​(java.io.File outputFile,
                                     JsonEncoding enc)
                              throws java.io.IOException
        Factory method for constructing properly initialized JsonGenerator to write content to specified File, using specified encoding. Generator is not managed (or "owned") by ObjectWriter: caller is responsible for properly closing it once content generation is complete.
        Throws:
        java.io.IOException
        Since:
        2.11

      • createGenerator

        public JsonGenerator createGenerator​(java.io.DataOutput out)
                              throws java.io.IOException
        Factory method for constructing properly initialized JsonGenerator to write content using specified DataOutput. Generator is not managed (or "owned") by ObjectWriter: caller is responsible for properly closing it once content generation is complete.
        Throws:
        java.io.IOException
        Since:
        2.11

      • writeValues

        public SequenceWriter writeValues​(java.io.File out)
                           throws java.io.IOException
        Method for creating a SequenceWriter to write a sequence of root values using configuration of this ObjectWriter. Sequence is not surrounded by JSON array; some backend types may not support writing of such sequences as root level. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.
        Parameters:
        out - Target file to write value sequence to.
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValues

        public SequenceWriter writeValues​(JsonGenerator g)
                           throws java.io.IOException
        Method for creating a SequenceWriter to write a sequence of root values using configuration of this ObjectWriter. Sequence is not surrounded by JSON array; some backend types may not support writing of such sequences as root level. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure that all content gets flushed by the generator. However, since a JsonGenerator is explicitly passed, it will NOT be closed when SequenceWriter.close() is called.
        Parameters:
        g - Low-level generator caller has already constructed that will be used for actual writing of token stream.
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValues

        public SequenceWriter writeValues​(java.io.Writer out)
                           throws java.io.IOException
        Method for creating a SequenceWriter to write a sequence of root values using configuration of this ObjectWriter. Sequence is not surrounded by JSON array; some backend types may not support writing of such sequences as root level. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.
        Parameters:
        out - Target writer to use for writing the token stream
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValues

        public SequenceWriter writeValues​(java.io.OutputStream out)
                           throws java.io.IOException
        Method for creating a SequenceWriter to write a sequence of root values using configuration of this ObjectWriter. Sequence is not surrounded by JSON array; some backend types may not support writing of such sequences as root level. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.
        Parameters:
        out - Physical output stream to use for writing the token stream
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValues

        public SequenceWriter writeValues​(java.io.DataOutput out)
                           throws java.io.IOException
        Throws:
        java.io.IOException
        Since:
        2.8

      • writeValuesAsArray

        public SequenceWriter writeValuesAsArray​(java.io.File out)
                                  throws java.io.IOException
        Method for creating a SequenceWriter to write an array of root-level values, using configuration of this ObjectWriter. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.

        Note that the type to use with forType(Class) needs to be type of individual values (elements) to write and NOT matching array or Collection type.

        Parameters:
        out - File to write token stream to
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValuesAsArray

        public SequenceWriter writeValuesAsArray​(JsonGenerator gen)
                                  throws java.io.IOException
        Method for creating a SequenceWriter to write an array of root-level values, using configuration of this ObjectWriter. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure that all content gets flushed by the generator. However, since a JsonGenerator is explicitly passed, it will NOT be closed when SequenceWriter.close() is called.

        Note that the type to use with forType(Class) needs to be type of individual values (elements) to write and NOT matching array or Collection type.

        Parameters:
        gen - Underlying generator to use for writing the token stream
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValuesAsArray

        public SequenceWriter writeValuesAsArray​(java.io.Writer out)
                                  throws java.io.IOException
        Method for creating a SequenceWriter to write an array of root-level values, using configuration of this ObjectWriter. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.

        Note that the type to use with forType(Class) needs to be type of individual values (elements) to write and NOT matching array or Collection type.

        Parameters:
        out - Writer to use for writing the token stream
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValuesAsArray

        public SequenceWriter writeValuesAsArray​(java.io.OutputStream out)
                                  throws java.io.IOException
        Method for creating a SequenceWriter to write an array of root-level values, using configuration of this ObjectWriter. Resulting writer needs to be SequenceWriter.close()d after all values have been written to ensure closing of underlying generator and output stream.

        Note that the type to use with forType(Class) needs to be type of individual values (elements) to write and NOT matching array or Collection type.

        Parameters:
        out - Physical output stream to use for writing the token stream
        Throws:
        java.io.IOException
        Since:
        2.5

      • writeValuesAsArray

        public SequenceWriter writeValuesAsArray​(java.io.DataOutput out)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
        Since:
        2.8

      • isEnabled

        @Deprecated
public boolean isEnabled​(JsonParser.Feature f)
        Deprecated.
        Since:
        2.9

      • getFactory

        public JsonFactory getFactory()
        Since:
        2.2

      • hasPrefetchedSerializer

        public boolean hasPrefetchedSerializer()
        Diagnostics method that can be called to check whether this writer has pre-fetched serializer to use: pre-fetching improves performance when writer instances are reused as it avoids a per-call serializer lookup.
        Since:
        2.2

      • writeValue

        public void writeValue​(JsonGenerator g,
                       java.lang.Object value)
                throws java.io.IOException
        Method that can be used to serialize any Java value as JSON output, using provided JsonGenerator.

        Note that the given JsonGenerator is not closed; caller is expected to handle that as necessary.

        Throws:
        java.io.IOException

      • writeValue

        public void writeValue​(java.io.OutputStream out,
                       java.lang.Object value)
                throws java.io.IOException,
                       StreamWriteException,
                       DatabindException
        Method that can be used to serialize any Java value as JSON output, using output stream provided (using encoding JsonEncoding.UTF8).

        Note: method does not close the underlying stream explicitly here; however, JsonFactory this mapper uses may choose to close the stream depending on its settings (by default, it will try to close it when JsonGenerator we construct is closed).

        Throws:
        java.io.IOException
        StreamWriteException
        DatabindException

      • writeValue

        public void writeValue​(java.io.Writer w,
                       java.lang.Object value)
                throws java.io.IOException,
                       StreamWriteException,
                       DatabindException
        Method that can be used to serialize any Java value as JSON output, using Writer provided.

        Note: method does not close the underlying stream explicitly here; however, JsonFactory this mapper uses may choose to close the stream depending on its settings (by default, it will try to close it when JsonGenerator we construct is closed).

        Throws:
        java.io.IOException
        StreamWriteException
        DatabindException

      • writeValueAsString

        public java.lang.String writeValueAsString​(java.lang.Object value)
                                    throws JsonProcessingException
        Method that can be used to serialize any Java value as a String. Functionally equivalent to calling writeValue(Writer,Object) with StringWriter and constructing String, but more efficient.

        Note: prior to version 2.1, throws clause included IOException; 2.1 removed it.

        Throws:
        JsonProcessingException

      • writeValueAsBytes

        public byte[] writeValueAsBytes​(java.lang.Object value)
                         throws JsonProcessingException
        Method that can be used to serialize any Java value as a byte array. Functionally equivalent to calling writeValue(Writer,Object) with ByteArrayOutputStream and getting bytes, but more efficient. Encoding used will be UTF-8.

        Note: prior to version 2.1, throws clause included IOException; 2.1 removed it.

        Throws:
        JsonProcessingException

      • acceptJsonFormatVisitor

        public void acceptJsonFormatVisitor​(JavaType type,
                                    JsonFormatVisitorWrapper visitor)
                             throws JsonMappingException
        Method for visiting type hierarchy for given type, using specified visitor. Visitation uses Serializer hierarchy and related properties

        This method can be used for things like generating Json Schema instance for specified type.

        Parameters:
        type - Type to generate schema for (possibly with generic signature)
        Throws:
        JsonMappingException
        Since:
        2.2

      • canSerialize

        public boolean canSerialize​(java.lang.Class<?> type)

      • canSerialize

        public boolean canSerialize​(java.lang.Class<?> type,
                            java.util.concurrent.atomic.AtomicReference<java.lang.Throwable> cause)
        Method for checking whether instances of given type can be serialized, and optionally why (as per Throwable returned).
        Since:
        2.3