Package org.apache.uima.json

# Class JsonCasSerializer

java.lang.Object
org.apache.uima.json.JsonCasSerializer

public class JsonCasSerializer extends Object

## CAS serializer for JSON formats.

Writes a CAS in a JSON format.

To use,

- create an instance of this class,
- (optionally) configure the instance, and then
- call serialize on the instance, optionally passing in additional parameters.

After the 1st 2 steps, the serializer instance may be used for multiple calls (on multiple threads) to the 3rd serialize step, if all calls use the same configuration.

There are "convenience" static serialize methods that do these three steps for common configurations.

Parameters can be configured in this instance (I), and/or as part of the serialize(S) call.

The parameters that can be configured are:

- (S) The CAS to serialize
- (S) where to put the output - an OutputStream, Writer, or File
- (I,S) a type system - (default null) if supplied, it is used to "filter" types and features that are serialized. If provided, only those that exist in the passed in type system are included in the serialization
- (I,S) a flag for prettyprinting - default false (no prettyprinting)

For Json serialization, additional configuration from the Jackson implementation can be configured

on 2 associated Jackson instances:

- JsonFactory
- JsonGenerator

using the standard Jackson methods on the associated JsonFactory instance; see the Jackson JsonFactory and JsonGenerator javadocs for details.

These 2 Jackson objects are settable/gettable from an instance of this class. They are created if not supplied by the caller.

Once this instance is configured, the serialize method is called to serialized a CAS to an output.

Instances of this class must be used on only one thread while configuration is being done; afterwards, multiple threads may use the configured instance, to call serialize.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `JsonCasSerializer.JsonContextFormat`
  The serialization can optionally include context information in addition to the feature structures.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JsonCasSerializer()`
  Creates a new JsonCasSerializer

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `jsonSerialize(CAS aCAS, Object output)`
  Serializes a CAS using JSON
  `static void`
  `jsonSerialize(CAS aCAS, TypeSystem aTargetTypeSystem, Object output)`
  Serializes a CAS to an output (File, OutputStream, XMI stream, or Writer).
  `static void`
  `jsonSerialize(CAS aCAS, TypeSystem aTargetTypeSystem, Object output, boolean aPrettyPrint, Marker aMarker, XmiSerializationSharedData sharedData)`
  Serializes a Delta CAS to an output (File, Writer, or OutputStream).
  `void`
  `serialize(CAS cas, Object output)`
  Serialize a Cas to an Output, using configurations set on this instance.
  `void`
  `serialize(CAS cas, Object output, XmiSerializationSharedData sharedData, Marker marker)`
  `void`
  `serialize(CAS cas, JsonContentHandlerJacksonWrapper jch)`
  Serialize a Cas to an Output configured in the passed in JsonContentHandlerJacksonWrapper Constructs a new CasDocSerializer instance to do the serialization, configured using this class's Delta marker setting (if any)
  `void`
  `serialize(CAS cas, JsonContentHandlerJacksonWrapper jch, XmiSerializationSharedData sharedData, Marker marker)`
  `JsonCasSerializer`
  `setErrorHandler(ErrorHandler eh)`
  set an error handler to receive information about errors
  `JsonCasSerializer`
  `setFilterTypes(TypeSystemImpl ts)`
  pass in a type system to use for filtering what gets serialized; only those types and features which are defined this type system are included.
  `JsonCasSerializer`
  `setJsonContext(JsonCasSerializer.JsonContextFormat format)`
  sets which Json context format to use when serializing
  `JsonCasSerializer`
  `setJsonFactory(com.fasterxml.jackson.core.JsonFactory jsonFactory)`
  set which JsonFactory instance to use; if null, a new instance is used this can be used to preconfigure the JsonFactory instance
  `JsonCasSerializer`
  `setOmit0Values(boolean omitDefaultValues)`
  `JsonCasSerializer`
  `setPrettyPrint(boolean pp)`
  set or reset the pretty print flag (default is false)
  `JsonCasSerializer`
  `setStaticEmbedding()`
  Sets static embedding mode
  `JsonCasSerializer`
  `setTypeSystemReference(String reference)`

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

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

- ## Constructor Details

  - ### JsonCasSerializer

    public JsonCasSerializer()
    Creates a new JsonCasSerializer

- ## Method Details

  - ### jsonSerialize

    public static void jsonSerialize(CAS aCAS, Object output) throws IOException
    Serializes a CAS using JSON
    Parameters:
      `aCAS` - CAS to serialize.
      `output` - a File, OutputStream or Writer to which to write the XMI document
    Throws:
      `IOException` - if there was an IOException

  - ### jsonSerialize

    public static void jsonSerialize(CAS aCAS, TypeSystem aTargetTypeSystem, Object output) throws IOException
    Serializes a CAS to an output (File, OutputStream, XMI stream, or Writer). The supplied typesystem filters the output
    Parameters:
      `aCAS` - CAS to serialize.
      `aTargetTypeSystem` - type system used for filtering what gets serialized. Any types or features not in the target type system will not be serialized. A null value indicates no filtering, that is, that all types and features will be serialized.
      `output` - output (File, OutputStream, or Writer) to which to write the JSON document
    Throws:
      `IOException` - if there was an IOException

  - ### jsonSerialize

    public static void jsonSerialize(CAS aCAS, TypeSystem aTargetTypeSystem, Object output, boolean aPrettyPrint, Marker aMarker, XmiSerializationSharedData sharedData) throws IOException
    Serializes a Delta CAS to an output (File, Writer, or OutputStream). This version of this method allows many options to be configured.
    Parameters:
      `aCAS` - CAS to serialize.
      `aTargetTypeSystem` - type system to which the produced XMI will conform. Any types or features not in the target type system will not be serialized. A null value indicates that all types and features will be serialized.
      `output` - File, Writer, or OutputStream to which to write the JSON document
      `aPrettyPrint` - if true the JSON output will be formatted with newlines and indenting. If false it will be unformatted.
      `aMarker` - an optional object used to determine which FeatureStructures and modifications were created after the mark was set. Used to serialize a Delta CAS consisting of only new FSs and views and preexisting FSs and Views that have been modified. If null, full serialization is done. See the JavaDocs for `Marker` for details.
      `sharedData` - optional, used for delta serialization (not yet supported)
    Throws:
      `IOException` - if there was an IOException

  - ### serialize

    public void serialize(CAS cas, Object output) throws IOException
    Serialize a Cas to an Output, using configurations set on this instance. Constructs a JsonContentHandlerJacksonWrapper, using configured JsonFactory and prettyprint settings if any
    Parameters:
      `cas` - - the CAS to serialize
      `output` - - where the output goes, an OutputStream, Writer, or File
    Throws:
      `IOException` - if there was an IOException

  - ### serialize

    public void serialize(CAS cas, Object output, XmiSerializationSharedData sharedData, Marker marker) throws IOException
    Throws:
      `IOException`

  - ### serialize

    public void serialize(CAS cas, JsonContentHandlerJacksonWrapper jch) throws IOException
    Serialize a Cas to an Output configured in the passed in JsonContentHandlerJacksonWrapper Constructs a new CasDocSerializer instance to do the serialization, configured using this class's Delta marker setting (if any)
    Parameters:
      `cas` - The CAS to serialize
      `jch` - the configured content handler
    Throws:
      `IOException` - if there was an IOException

  - ### serialize

    public void serialize(CAS cas, JsonContentHandlerJacksonWrapper jch, XmiSerializationSharedData sharedData, Marker marker) throws IOException
    Throws:
      `IOException`

  - ### setPrettyPrint

    public JsonCasSerializer setPrettyPrint(boolean pp)
    set or reset the pretty print flag (default is false)
    Parameters:
      `pp` - true to do pretty printing of output
    Returns:
      the original instance, possibly updated

  - ### setJsonFactory

    public JsonCasSerializer setJsonFactory(com.fasterxml.jackson.core.JsonFactory jsonFactory)
    set which JsonFactory instance to use; if null, a new instance is used this can be used to preconfigure the JsonFactory instance
    Parameters:
      `jsonFactory` - -
    Returns:
      the original instance, possibly updated

  - ### setFilterTypes

    public JsonCasSerializer setFilterTypes(TypeSystemImpl ts)
    pass in a type system to use for filtering what gets serialized; only those types and features which are defined this type system are included.
    Parameters:
      `ts` - the filter
    Returns:
      the original instance, possibly updated

  - ### setTypeSystemReference

    public JsonCasSerializer setTypeSystemReference(String reference)

  - ### setErrorHandler

    public JsonCasSerializer setErrorHandler(ErrorHandler eh)
    set an error handler to receive information about errors
    Parameters:
      `eh` - the error handler
    Returns:
      the original instance, possibly updated

  - ### setStaticEmbedding

    public JsonCasSerializer setStaticEmbedding()
    Sets static embedding mode
    Returns:
      the original instance, possibly updated

  - ### setJsonContext

    public JsonCasSerializer setJsonContext(JsonCasSerializer.JsonContextFormat format)
    sets which Json context format to use when serializing
    Parameters:
      `format` - the format to use for the serialization Specifying the context flag also specifies all 3 subflags Specifying one of the subflags as true sets the context flag to true if it isn't already
    Returns:
      the original instance, possibly updated

  - ### setOmit0Values

    public JsonCasSerializer setOmit0Values(boolean omitDefaultValues)