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

org.codehaus.jackson.map

## Class ObjectWriter

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

- All Implemented Interfaces:
    Versioned

      public class ObjectWriter
      extends Object
      implements Versioned

  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
  Since:
    1.5
  Author:
    tatu

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected SerializationConfig` | `_config` General serialization configuration settings
    `protected JsonFactory` | `_jsonFactory` Factory used for constructing `JsonGenerator`s
    `protected PrettyPrinter` | `_prettyPrinter` To allow for dynamic enabling/disabling of pretty printing, pretty printer can be optionally configured for writer as well
    `protected SerializerProvider` | `_provider`
    `protected JavaType` | `_rootType` Specified root serialization type to use; can be same as runtime type, but usually one of its super types
    `protected FormatSchema` | `_schema` When using data format that uses a schema, schema is passed to generator.
    `protected SerializerFactory` | `_serializerFactory`
    `protected static PrettyPrinter` | `NULL_PRETTY_PRINTER` We need to keep track of explicit disabling of pretty printing; easiest to do by a token value.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ObjectWriter(ObjectMapper mapper, SerializationConfig config)` Alternative constructor for initial instantiation.
    `protected` | `ObjectWriter(ObjectMapper mapper, SerializationConfig config, FormatSchema s)` Alternative constructor for initial instantiation.
    `protected` | `ObjectWriter(ObjectMapper mapper, SerializationConfig config, JavaType rootType, PrettyPrinter pp)` Constructor used by `ObjectMapper` for initial instantiation
    `protected` | `ObjectWriter(ObjectWriter base, SerializationConfig config)` Copy constructor used for building variations.
    `protected` | `ObjectWriter(ObjectWriter base, SerializationConfig config, JavaType rootType, PrettyPrinter pp, FormatSchema s)` Copy constructor used for building variations.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_configAndWriteValue(JsonGenerator jgen, Object value)` Method called to configure the generator as necessary and then call write functionality
    `boolean` | `canSerialize(Class<?> type)`
    `Version` | `version()` Method that will return version information stored in and read from jar that contains this class.
    `ObjectWriter` | `withDateFormat(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.
    `ObjectWriter` | `withDefaultPrettyPrinter()` Method that will construct a new instance that will use the default pretty printer for serialization.
    `ObjectWriter` | `withFilters(FilterProvider filterProvider)` Method that will construct a new instance that uses specified provider for resolving filter instances by id.
    `ObjectWriter` | `withPrettyPrinter(PrettyPrinter pp)` Method that will construct a new instance that will use specified pretty printer (or, if null, will not do any pretty-printing)
    `ObjectWriter` | `withSchema(FormatSchema schema)`
    `ObjectWriter` | `withType(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.
    `ObjectWriter` | `withType(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.
    `ObjectWriter` | `withType(TypeReference<?> rootType)`
    `ObjectWriter` | `withView(Class<?> view)` Method that will construct a new instance that uses specified serialization view for serialization (with null basically disables view processing)
    `void` | `writeValue(File resultFile, Object value)` Method that can be used to serialize any Java value as JSON output, written to File provided.
    `void` | `writeValue(JsonGenerator jgen, Object value)` Method that can be used to serialize any Java value as JSON output, using provided `JsonGenerator`.
    `void` | `writeValue(OutputStream out, Object value)` Method that can be used to serialize any Java value as JSON output, using output stream provided (using encoding `JsonEncoding.UTF8`).
    `void` | `writeValue(Writer w, Object value)` Method that can be used to serialize any Java value as JSON output, using Writer provided.
    `byte[]` | `writeValueAsBytes(Object value)` Method that can be used to serialize any Java value as a byte array.
    `String` | `writeValueAsString(Object value)` Method that can be used to serialize any Java value as a String.

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

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

- - ### Field Detail

    - #### NULL_PRETTY_PRINTER

          protected static final PrettyPrinter NULL_PRETTY_PRINTER

      We need to keep track of explicit disabling of pretty printing; easiest to do by a token value.

    - #### _config

          protected final SerializationConfig _config

      General serialization configuration settings

    - #### _provider

          protected final SerializerProvider _provider

    - #### _serializerFactory

          protected final SerializerFactory _serializerFactory

    - #### _jsonFactory

          protected final JsonFactory _jsonFactory

      Factory used for constructing `JsonGenerator`s

    - #### _rootType

          protected final JavaType _rootType

      Specified root serialization type to use; can be same as runtime type, but usually one of its super types

    - #### _prettyPrinter

          protected final PrettyPrinter _prettyPrinter

      To allow for dynamic enabling/disabling of pretty printing, pretty printer can be optionally configured for writer as well

    - #### _schema

          protected final FormatSchema _schema

      When using data format that uses a schema, schema is passed to generator.
      Since:
        1.8

  - ### Constructor Detail

    - #### ObjectWriter

          protected ObjectWriter(ObjectMapper mapper,
                      SerializationConfig config,
                      JavaType rootType,
                      PrettyPrinter pp)

      Constructor used by `ObjectMapper` for initial instantiation

    - #### ObjectWriter

          protected ObjectWriter(ObjectMapper mapper,
                      SerializationConfig config)

      Alternative constructor for initial instantiation.
      Since:
        1.7

    - #### ObjectWriter

          protected ObjectWriter(ObjectMapper mapper,
                      SerializationConfig config,
                      FormatSchema s)

      Alternative constructor for initial instantiation.
      Since:
        1.7

    - #### ObjectWriter

          protected ObjectWriter(ObjectWriter base,
                      SerializationConfig config,
                      JavaType rootType,
                      PrettyPrinter pp,
                      FormatSchema s)

      Copy constructor used for building variations.

    - #### ObjectWriter

          protected ObjectWriter(ObjectWriter base,
                      SerializationConfig config)

      Copy constructor used for building variations.
      Since:
        1.7

  - ### 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`
      Since:
        1.6

    - #### withView

          public ObjectWriter withView(Class<?> view)

      Method that will construct a new instance that uses specified serialization view for serialization (with null basically disables view processing)

    - #### withType

          public ObjectWriter withType(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.

    - #### withType

          public ObjectWriter withType(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.

    - #### withType

          public ObjectWriter withType(TypeReference<?> rootType)

      Since:
        1.7

    - #### withPrettyPrinter

          public ObjectWriter withPrettyPrinter(PrettyPrinter pp)

      Method that will construct a new instance that will use specified pretty printer (or, if null, will not do any pretty-printing)
      Since:
        1.6

    - #### withDefaultPrettyPrinter

          public ObjectWriter withDefaultPrettyPrinter()

      Method that will construct a new instance that will use the default pretty printer for serialization.
      Since:
        1.6

    - #### withFilters

          public ObjectWriter withFilters(FilterProvider filterProvider)

      Method that will construct a new instance that uses specified provider for resolving filter instances by id.
      Since:
        1.7

    - #### withSchema

          public ObjectWriter withSchema(FormatSchema schema)

      Since:
        1.8

    - #### withDateFormat

          public ObjectWriter withDateFormat(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.
      Since:
        1.9

    - #### writeValue

          public void writeValue(JsonGenerator jgen,
                        Object value)
                          throws IOException,
                                 JsonGenerationException,
                                 JsonMappingException

      Method that can be used to serialize any Java value as JSON output, using provided `JsonGenerator`.
      Throws:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### writeValue

          public void writeValue(File resultFile,
                        Object value)
                          throws IOException,
                                 JsonGenerationException,
                                 JsonMappingException

      Method that can be used to serialize any Java value as JSON output, written to File provided.
      Throws:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### writeValue

          public void writeValue(OutputStream out,
                        Object value)
                          throws IOException,
                                 JsonGenerationException,
                                 JsonMappingException

      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:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### writeValue

          public void writeValue(Writer w,
                        Object value)
                          throws IOException,
                                 JsonGenerationException,
                                 JsonMappingException

      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:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### writeValueAsString

          public String writeValueAsString(Object value)
                                    throws IOException,
                                           JsonGenerationException,
                                           JsonMappingException

      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.
      Throws:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### writeValueAsBytes

          public byte[] writeValueAsBytes(Object value)
                                   throws IOException,
                                          JsonGenerationException,
                                          JsonMappingException

      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.
      Throws:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`

    - #### canSerialize

          public boolean canSerialize(Class<?> type)

    - #### _configAndWriteValue

          protected final void _configAndWriteValue(JsonGenerator jgen,
                                  Object value)
                                             throws IOException,
                                                    JsonGenerationException,
                                                    JsonMappingException

      Method called to configure the generator as necessary and then call write functionality
      Throws:
        `IOException`
        `JsonGenerationException`
        `JsonMappingException`