org.apache.uima.cas.impl

Class XmiCasSerializer

java.lang.Object

org.apache.uima.cas.impl.XmiCasSerializer

public class XmiCasSerializer
extends Object

CAS serializer for XMI format; writes a CAS in the XML Metadata Interchange (XMI) 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 the XmiCasSerializer 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
• (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)
• (I) (optional) If supplied, a map used to generate a "schemaLocation" attribute in the XMI output. This argument must be a map from namespace URIs to the schema location for that namespace URI.
• (S) (optional) if supplied XmiSerializationSharedData representing FeatureStructures that were set aside when deserializing, and are to be "merged" back in when serializing
• (S) a Marker (default: null) if supplied, where the separation between "new" and previously exisiting FeatureStructures are in the CAS; causes "delta" serialization, where only the new and changed FeatureStructures are serialized.

Once the XmiCasSerializer 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.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_NAMESPACE_URI Namespace URI to use for UIMA types that have no namespace (the "default pacakge" in Java)
static String	ID_ATTR_NAME
static String	SYSTEM_LINE_FEED
static String	XMI_NS_PREFIX
static String	XMI_NS_URI
static org.apache.uima.internal.util.XmlElementName	XMI_TAG
static String	XMI_TAG_LOCAL_NAME
static String	XMI_TAG_QNAME
static String	XMI_VERSION_LOCAL_NAME
static String	XMI_VERSION_QNAME
static String	XMI_VERSION_VALUE
static String	XMLNS_NS_URI
static String	XSI_NS_URI

Constructor Summary

Constructors

Constructor and Description
XmiCasSerializer(TypeSystem ts) Creates a new XmiCasSerializer.
XmiCasSerializer(TypeSystem ts, Map<String,String> nsUriToSchemaLocationMap) Creates a new XmiCasSerializer.
XmiCasSerializer(TypeSystem ts, Map<String,String> nsUriToSchemaLocationMap, boolean isFormattedOutput) Creates a new XmiCasSerializer
XmiCasSerializer(TypeSystem ts, UimaContext uimaContext) Deprecated. Use XmiCasSerializer(TypeSystem) instead. The UimaContext reference is never used by this implementation.
XmiCasSerializer(TypeSystem ts, UimaContext uimaContext, Map<String,String> nsUriToSchemaLocationMap) Deprecated. Use XmiCasSerializer(TypeSystem, Map) instead. The UimaContext reference is never used by this implementation.

Method Summary

Modifier and Type	Method and Description
void	serialize(CAS cas, ContentHandler contentHandler) Write the CAS data to a SAX content handler.
void	serialize(CAS cas, ContentHandler contentHandler, ErrorHandler errorHandler) Write the CAS data to a SAX content handler.
void	serialize(CAS cas, ContentHandler contentHandler, ErrorHandler errorHandler, XmiSerializationSharedData sharedData) Write the CAS data to a SAX content handler.
void	serialize(CAS cas, ContentHandler contentHandler, ErrorHandler errorHandler, XmiSerializationSharedData sharedData, Marker marker) Write the CAS data to a SAX content handler.
static void	serialize(CAS aCAS, OutputStream aStream) Serializes a CAS to an XMI stream.
static void	serialize(CAS aCAS, TypeSystem aTargetTypeSystem, OutputStream aStream) Serializes a CAS to an XMI stream.
static void	serialize(CAS aCAS, TypeSystem aTargetTypeSystem, OutputStream aStream, boolean aPrettyPrint, XmiSerializationSharedData aSharedData) Serializes a CAS to an XMI stream.
static void	serialize(CAS aCAS, TypeSystem aTargetTypeSystem, OutputStream aStream, boolean aPrettyPrint, XmiSerializationSharedData aSharedData, Marker aMarker) Serializes a Delta CAS to an XMI stream.
XmiCasSerializer	setErrorHandler(ErrorHandler eh) set an error handler to receive information about errors
XmiCasSerializer	setFilterTypes(org.apache.uima.cas.impl.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.
XmiCasSerializer	setPrettyPrint(boolean pp) set or reset the pretty print flag (default is false)

Methods inherited from class java.lang.Object

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

Field Detail

XMLNS_NS_URI

public static final String XMLNS_NS_URI

See Also:

Constant Field Values

XMI_NS_URI

public static final String XMI_NS_URI

See Also:

Constant Field Values

XSI_NS_URI

public static final String XSI_NS_URI

See Also:

Constant Field Values

XMI_NS_PREFIX

public static final String XMI_NS_PREFIX

See Also:

Constant Field Values

ID_ATTR_NAME

public static final String ID_ATTR_NAME

See Also:

Constant Field Values

XMI_TAG_LOCAL_NAME

public static final String XMI_TAG_LOCAL_NAME

See Also:

Constant Field Values

XMI_TAG_QNAME

public static final String XMI_TAG_QNAME

See Also:

Constant Field Values

XMI_TAG

public static final org.apache.uima.internal.util.XmlElementName XMI_TAG

XMI_VERSION_LOCAL_NAME

public static final String XMI_VERSION_LOCAL_NAME

See Also:

Constant Field Values

XMI_VERSION_QNAME

public static final String XMI_VERSION_QNAME

See Also:

Constant Field Values

XMI_VERSION_VALUE

public static final String XMI_VERSION_VALUE

See Also:

Constant Field Values

DEFAULT_NAMESPACE_URI

public static final String DEFAULT_NAMESPACE_URI

Namespace URI to use for UIMA types that have no namespace (the "default pacakge" in Java)

See Also:

Constant Field Values

SYSTEM_LINE_FEED

public static final String SYSTEM_LINE_FEED

Constructor Detail

XmiCasSerializer

public XmiCasSerializer(TypeSystem ts)

Creates a new XmiCasSerializer.

Parameters:

ts - An optional typeSystem (or null) to filter the types that will be serialized. If any CAS that is later passed to the serialize method that contains types and features that are not in this typesystem, the serialization will not contain instances of those types or values for those features. So this can be used to filter the results of serialization. A null value indicates that all types and features will be serialized.

XmiCasSerializer

public XmiCasSerializer(TypeSystem ts,
                        Map<String,String> nsUriToSchemaLocationMap)

Creates a new XmiCasSerializer.

Parameters:

ts - An optional typeSystem (or null) to filter the types that will be serialized. If any CAS that is later passed to the serialize method that contains types and features that are not in this typesystem, the serialization will not contain instances of those types or values for those features. So this can be used to filter the results of serialization.

nsUriToSchemaLocationMap - Map if supplied, this map is used to generate a "schemaLocation" attribute in the XMI output. This argument must be a map from namespace URIs to the schema location for that namespace URI.

XmiCasSerializer

public XmiCasSerializer(TypeSystem ts,
                        Map<String,String> nsUriToSchemaLocationMap,
                        boolean isFormattedOutput)

Creates a new XmiCasSerializer

Parameters:

ts - An optional typeSystem (or null) to filter the types that will be serialized. If any CAS that is later passed to the serialize method that contains types and features that are not in this typesystem, the serialization will not contain instances of those types or values for those features. So this can be used to filter the results of serialization.

nsUriToSchemaLocationMap - Map if supplied, this map is used to generate a "schemaLocation" attribute in the XMI output. This argument must be a map from namespace URIs to the schema location for that namespace URI.

isFormattedOutput - true makes serialization pretty print

XmiCasSerializer

@Deprecated
public XmiCasSerializer(TypeSystem ts,
                                     UimaContext uimaContext,
                                     Map<String,String> nsUriToSchemaLocationMap)

Deprecated. Use XmiCasSerializer(TypeSystem, Map) instead. The UimaContext reference is never used by this implementation.

Creates a new XmiCasSerializer.

Parameters:

ts - An optional typeSystem (or null) to filter the types that will be serialized. If any CAS that is later passed to the serialize method that contains types and features that are not in this typesystem, the serialization will not contain instances of those types or values for those features. So this can be used to filter the results of serialization.

uimaContext - not used

nsUriToSchemaLocationMap - Map if supplied, this map is used to generate a "schemaLocation" attribute in the XMI output. This argument must be a map from namespace URIs to the schema location for that namespace URI.

XmiCasSerializer

@Deprecated
public XmiCasSerializer(TypeSystem ts,
                                     UimaContext uimaContext)

Deprecated. Use XmiCasSerializer(TypeSystem) instead. The UimaContext reference is never used by this implementation.

Creates a new XmiCasSerializer.

Parameters:

ts - An optional typeSystem (or null) to filter the types that will be serialized. If any CAS that is later passed to the serialize method that contains types and features that are not in this typesystem, the serialization will not contain instances of those types or values for those features. So this can be used to filter the results of serialization.

uimaContext - not used

Method Detail

serialize

public static void serialize(CAS aCAS,
                             OutputStream aStream)
                      throws SAXException

Serializes a CAS to an XMI stream.

Parameters:

aCAS - CAS to serialize.

aStream - output stream to which to write the XMI document

Throws:

SAXException - if a problem occurs during XMI serialization

serialize

public static void serialize(CAS aCAS,
                             TypeSystem aTargetTypeSystem,
                             OutputStream aStream)
                      throws SAXException

Serializes a CAS to an XMI stream. Allows a TypeSystem to be specified, to which the produced XMI will conform. Any types or features not in the target type system will not be serialized.

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.

aStream - output stream to which to write the XMI document

Throws:

SAXException - if a problem occurs during XMI serialization

serialize

public static void serialize(CAS aCAS,
                             TypeSystem aTargetTypeSystem,
                             OutputStream aStream,
                             boolean aPrettyPrint,
                             XmiSerializationSharedData aSharedData)
                      throws SAXException

Serializes a CAS to an XMI stream. 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.

aStream - output stream to which to write the XMI document

aPrettyPrint - if true the XML output will be formatted with newlines and indenting. If false it will be unformatted.

aSharedData - an optional container for data that is shared between the XmiCasSerializer and the XmiCasDeserializer. See the JavaDocs for XmiSerializationSharedData for details.

Throws:

SAXException - if a problem occurs during XMI serialization

serialize

public static void serialize(CAS aCAS,
                             TypeSystem aTargetTypeSystem,
                             OutputStream aStream,
                             boolean aPrettyPrint,
                             XmiSerializationSharedData aSharedData,
                             Marker aMarker)
                      throws SAXException

Serializes a Delta CAS to an XMI stream. 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.

aStream - output stream to which to write the XMI document

aPrettyPrint - if true the XML output will be formatted with newlines and indenting. If false it will be unformatted.

aSharedData - an optional container for data that is shared between the XmiCasSerializer and the XmiCasDeserializer. See the JavaDocs for XmiSerializationSharedData for details.

aMarker - an optional object that is used to filter and serialize a Delta CAS containing only those FSs and Views created after Marker was set and preexisting FSs and views that were modified. See the JavaDocs for Marker for details.

Throws:

SAXException - if a problem occurs during XMI serialization

serialize

public void serialize(CAS cas,
                      ContentHandler contentHandler)
               throws SAXException

Write the CAS data to a SAX content handler.

Parameters:

cas - The CAS to be serialized.

contentHandler - The SAX content handler the data is written to.

Throws:

SAXException - if there was a SAX exception

serialize

public void serialize(CAS cas,
                      ContentHandler contentHandler,
                      ErrorHandler errorHandler)
               throws SAXException

Write the CAS data to a SAX content handler.

Parameters:

cas - The CAS to be serialized.

contentHandler - The SAX content handler the data is written to.

errorHandler - the SAX Error Handler to use

Throws:

SAXException - if there was a SAX exception

serialize

public void serialize(CAS cas,
                      ContentHandler contentHandler,
                      ErrorHandler errorHandler,
                      XmiSerializationSharedData sharedData)
               throws SAXException

Write the CAS data to a SAX content handler.

Parameters:

cas - The CAS to be serialized.

contentHandler - The SAX content handler the data is written to.

sharedData - data structure used to allow the XmiCasSerializer and XmiCasDeserializer to share information.

errorHandler - the SAX Error Handler to use

Throws:

SAXException - if there was a SAX exception

serialize

public void serialize(CAS cas,
                      ContentHandler contentHandler,
                      ErrorHandler errorHandler,
                      XmiSerializationSharedData sharedData,
                      Marker marker)
               throws SAXException

Write the CAS data to a SAX content handler.

Parameters:

cas - The CAS to be serialized.

contentHandler - The SAX content handler the data is written to.

errorHandler - the SAX Error Handler to use

sharedData - data structure used to allow the XmiCasSerializer and XmiCasDeserializer to share information.

marker - an object used to filter the FSs and Views to determine if these 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.

Throws:

SAXException - if there was a SAX exception

setPrettyPrint

public XmiCasSerializer 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

setFilterTypes

public XmiCasSerializer setFilterTypes(org.apache.uima.cas.impl.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

setErrorHandler

public XmiCasSerializer setErrorHandler(ErrorHandler eh)

set an error handler to receive information about errors

Parameters:

eh - the error handler

Returns:

the original instance, possibly updated