com.luciad.format.xml.bind.schema

LuciadLightspeedClass TLcdXMLSchemaBasedEncoder

java.lang.Object

com.luciad.format.xml.bind.schema.TLcdXMLSchemaBasedEncoder

All Implemented Interfaces:

ILcdOutputStreamFactoryCapable

public class TLcdXMLSchemaBasedEncoder
extends Object
implements ILcdOutputStreamFactoryCapable

Encoder for marshalling a Java object graph into an XML Schema-based XML document, using ILcdXMLMarshaller's and ILcdXMLTypeMarshaller's.

This class is very similar in functionality to TLcdXMLEncoder, but adds extra support for XML schema:

• It has an additional provider for ILcdXMLTypeMarshaller's.
• It has an additional schema mapping, providing type object factories and schema information.
• Its TLcdXMLMarshallerProvider will use the XML Schema substitution group information from the XML Schema info to choose the best marshaller for each [XML element, Java class] pair.

Please refer to this package's documentation and the com.luciad.format.xml.bind package documentation for a general overview of the XML Binding Framework.

Since:

9.0

Constructor Summary

Constructors

Constructor and Description
TLcdXMLSchemaBasedEncoder() Creates a new, empty XML encoder.
TLcdXMLSchemaBasedEncoder(ILcdXMLSchemaBasedEncoderLibrary aLibrary) Creates an encoder for the specified encoder library.
TLcdXMLSchemaBasedEncoder(ILcdXMLSchemaBasedEncoderLibrary aLibrary, TLcdXMLSchemaBasedMapping aMapping) Creates an encoder for the specified encoder library.
TLcdXMLSchemaBasedEncoder(List<ILcdXMLSchemaBasedEncoderLibrary> aLibraries) Creates an encoder for the specified encoder libraries.
TLcdXMLSchemaBasedEncoder(List<ILcdXMLSchemaBasedEncoderLibrary> aLibraries, TLcdXMLSchemaBasedMapping aMapping) Creates an encoder for the specified encoder libraries.
TLcdXMLSchemaBasedEncoder(TLcdXMLSchemaBasedMapping aMapping) Creates a new, empty XML encoder.

Method Summary

Modifier and Type	Method and Description
void	configure(TLcdDataModel aDataModel) Configures this encoder for the given data model and all its dependencies.
ILcdXMLDocumentContext	createDocumentContext() Creates a new ILcdXMLDocumentContext that can be used during encoding of an XML document.
void	encode(Object aObject, OutputStream aDestination) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, OutputStream aDestination, ILcdXMLDocumentContext aDocumentContext) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, QName aRootElementSubstitutionGroup, OutputStream aDestination) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, QName aRootElementSubstitutionGroup, OutputStream aDestination, ILcdXMLDocumentContext aDocumentContext) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, QName aRootElementSubstitutionGroup, Result aResult, ILcdXMLDocumentContext aDocumentContext) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, QName aRootElementSubstitutionGroup, String aDestination, ILcdXMLDocumentContext aDocumentContext) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, Result aResult) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, Result aResult, ILcdXMLDocumentContext aDocumentContext) Marshals the specified Java object to XML data, written to the specified OutputStream.
void	encode(Object aObject, String aDestination) Marshals the specified Java object to XML data, written to the specified destination.
TLcdXMLSchemaBasedMapping	getMapping() Returns the TLcdXMLSchemaMapping associated with this encoder.
TLcdXMLSchemaBasedMarshallerProvider	getMarshallerProvider() Returns the marshaller provider for this encoder, containing marshallers for converting Java object graphs to XML data.
Map<String,String>	getNamespacePrefixes() Returns a map containing as keys the namespaces supported by this encoder, and as values their corresponding prefixes.
static Map<String,String>	getNamespacePrefixes(ILcdXMLDocumentContext aContext) Returns a mapping between name space and schema prefix.
Set<String>	getNamespaceURIs() Returns the set of namespaces which are supported by this encoder.
ILcdOutputStreamFactory	getOutputStreamFactory() Returns the com.luciad.io.ILcdOutputStreamFactory that is used by this encoder for creating output streams.
Map<String,String>	getSchemaLocations() Returns a map containing as keys the namespaces supported by this encoder, and as values their corresponding schema locations.
static Map<String,String>	getSchemaLocations(ILcdXMLDocumentContext aContext) Returns a mapping between name space and schema location.
TLcdXMLTypeMarshallerProvider	getTypeMarshallerProvider() Returns the schema type marshaller provider for this encoder, containing schema type marshallers for converting Java object graphs to XML data.
XMLOutputFactory	getXMLOutputFactory() Returns the javax.xml.stream.XMLOutputFactory that is used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.
void	registerNamespaceURI(String aNamespaceURI, String aPrefix, String aSchemaLocation) Registers the specified namespace on this encoder.
void	setOutputStreamFactory(ILcdOutputStreamFactory aOutputStreamFactory) Sets the com.luciad.io.ILcdOutputStreamFactory that is to be used by this encoder for creating output streams.
void	setXMLOutputFactory(XMLOutputFactory aXMLOutputFactory) Sets the javax.xml.stream.XMLOutputFactory to be used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder()

Creates a new, empty XML encoder.

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder(TLcdXMLSchemaBasedMapping aMapping)

Creates a new, empty XML encoder.

Parameters:

aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder(ILcdXMLSchemaBasedEncoderLibrary aLibrary)

Creates an encoder for the specified encoder library.

This is a convenience constructor, being identical to:

   TLcdXMLEncoder encoder = new TLcdXMLEncoder();
   aLibrary.configureEncoder( this );
 

Parameters:

aLibrary - the encoder library for which to create an encoder.

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder(List<ILcdXMLSchemaBasedEncoderLibrary> aLibraries)

Creates an encoder for the specified encoder libraries.

This is a convenience constructor, being identical to:

   TLcdXMLEncoder encoder = new TLcdXMLEncoder();
   for ( ILcdXMLEncoderLibrary library : aLibraries ) {
     library.configureEncoder( this );
   }
 

Parameters:

aLibraries - the encoder libraries for which to create an encoder.

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder(ILcdXMLSchemaBasedEncoderLibrary aLibrary,
                                 TLcdXMLSchemaBasedMapping aMapping)

Creates an encoder for the specified encoder library.

This is a convenience constructor, being identical to:

   TLcdXMLEncoder encoder = new TLcdXMLEncoder(aMapping);
   aLibrary.configureEncoder( this );
 

Parameters:

aLibrary - the encoder library for which to create an encoder.

aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

TLcdXMLSchemaBasedEncoder

public TLcdXMLSchemaBasedEncoder(List<ILcdXMLSchemaBasedEncoderLibrary> aLibraries,
                                 TLcdXMLSchemaBasedMapping aMapping)

Creates an encoder for the specified encoder libraries.

This is a convenience constructor, being identical to:

   TLcdXMLEncoder encoder = new TLcdXMLEncoder(aMapping);
   for ( ILcdXMLEncoderLibrary library : aLibraries ) {
     library.configureEncoder( this );
   }
 

Parameters:

aLibraries - the encoder libraries for which to create an encoder.

aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

Method Detail

getOutputStreamFactory

public ILcdOutputStreamFactory getOutputStreamFactory()

Returns the com.luciad.io.ILcdOutputStreamFactory that is used by this encoder for creating output streams.

Specified by:

getOutputStreamFactory in interface ILcdOutputStreamFactoryCapable

Returns:

the com.luciad.io.ILcdOutputStreamFactory that is used by this encoder for creating output streams.

setOutputStreamFactory

public void setOutputStreamFactory(ILcdOutputStreamFactory aOutputStreamFactory)

Sets the com.luciad.io.ILcdOutputStreamFactory that is to be used by this encoder for creating output streams.

Specified by:

setOutputStreamFactory in interface ILcdOutputStreamFactoryCapable

Parameters:

aOutputStreamFactory - the com.luciad.io.ILcdOutputStreamFactory that is to beused by this encoder for creating output streams.

getXMLOutputFactory

public XMLOutputFactory getXMLOutputFactory()

Returns the javax.xml.stream.XMLOutputFactory that is used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.

Returns:

the javax.xml.stream.XMLOutputFactory that is used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.

setXMLOutputFactory

public void setXMLOutputFactory(XMLOutputFactory aXMLOutputFactory)

Sets the javax.xml.stream.XMLOutputFactory to be used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.

Parameters:

aXMLOutputFactory - the javax.xml.stream.XMLOutputFactory to be used by this encoder for creating javax.xml.stream.XMLStreamWriter instances.

createDocumentContext

public ILcdXMLDocumentContext createDocumentContext()

Creates a new ILcdXMLDocumentContext that can be used during encoding of an XML document. A document context may only be used for encoding a single XML document and should be discarded afterwards.

Returns:

a new ILcdXMLDocumentContext that can be used during encoding of an XML document.

encode

public void encode(Object aObject,
                   String aDestination)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified destination.

Parameters:

aObject - the Java object to be marshalled.

aDestination - the data source to which the data should be written; typically a file name.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   QName aRootElementSubstitutionGroup,
                   String aDestination,
                   ILcdXMLDocumentContext aDocumentContext)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aRootElementSubstitutionGroup - the substitution group the root element of the resulting XML data should be part of.

aDestination - the data source to which the data should be written; typically a file name.

aDocumentContext - the document context to be used during marshalling.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   OutputStream aDestination)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aDestination - the OutputStream to which the resulting XML data should be written.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   Result aResult)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aResult - the Result to which the resulting XML data should be written.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

UnsupportedOperationException - in case the XMLOutputFactory doesn't support the given result.

encode

public void encode(Object aObject,
                   QName aRootElementSubstitutionGroup,
                   OutputStream aDestination)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aRootElementSubstitutionGroup - the substitution group the root element of the resulting XML data should be part of.

aDestination - the OutputStream to which the resulting XML data should be written.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   OutputStream aDestination,
                   ILcdXMLDocumentContext aDocumentContext)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aDestination - the OutputStream to which the resulting XML data should be written.

aDocumentContext - the document context to be used during marshalling.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   QName aRootElementSubstitutionGroup,
                   OutputStream aDestination,
                   ILcdXMLDocumentContext aDocumentContext)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aRootElementSubstitutionGroup - the substitution group the root element of the resulting XML data should be part of.

aDestination - the OutputStream to which the resulting XML data should be written.

aDocumentContext - the document context to be used during marshalling.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

encode

public void encode(Object aObject,
                   Result aResult,
                   ILcdXMLDocumentContext aDocumentContext)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aResult - the result to which the resulting XML data should be written.

aDocumentContext - the document context to be used during marshalling.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

UnsupportedOperationException - in case the XMLOutputFactory doesn't support the given result.

encode

public void encode(Object aObject,
                   QName aRootElementSubstitutionGroup,
                   Result aResult,
                   ILcdXMLDocumentContext aDocumentContext)
            throws XMLStreamException,
                   IOException

Marshals the specified Java object to XML data, written to the specified OutputStream.

Parameters:

aObject - the Java object to be marshalled.

aRootElementSubstitutionGroup - the substitution group the root element of the resulting XML data should be part of.

aResult - the result to which the resulting XML data should be written.

aDocumentContext - the document context to be used during marshalling.

Throws:

XMLStreamException - if an unexpected processing exception occurs during marshalling.

IOException - if an java.io.IOException occurs during marshalling.

getMarshallerProvider

public TLcdXMLSchemaBasedMarshallerProvider getMarshallerProvider()

Returns the marshaller provider for this encoder, containing marshallers for converting Java object graphs to XML data.

Returns:

the marshaller provider for this encoder.

getMapping

public TLcdXMLSchemaBasedMapping getMapping()

Returns the TLcdXMLSchemaMapping associated with this encoder. This mapping is used by the encoder to retrieve schema information and object factories.

Returns:

the TLcdXMLSchemaMapping associated with this decoder.

getTypeMarshallerProvider

public TLcdXMLTypeMarshallerProvider getTypeMarshallerProvider()

Returns the schema type marshaller provider for this encoder, containing schema type marshallers for converting Java object graphs to XML data.

Returns:

the schema type marshaller provider for this encoder.

getNamespaceURIs

public Set<String> getNamespaceURIs()

Returns the set of namespaces which are supported by this encoder.

Returns:

the set of namespaces which are supported by this encoder.

getSchemaLocations

public Map<String,String> getSchemaLocations()

Returns a map containing as keys the namespaces supported by this encoder, and as values their corresponding schema locations. These schema locations are encoded in the root element of all documents encoded by this encoder via the xsi:schemaLocations attribute.

Returns:

a map with all [namespace, schema location] pairs that should be included in each encoder document.

getNamespacePrefixes

public static Map<String,String> getNamespacePrefixes(ILcdXMLDocumentContext aContext)

Returns a mapping between name space and schema prefix. These name spaces are declared with their prefixes in the root element of all documents encoded with the given document context. When a name space occurs both in getNamespacePrefixes() and in the map returned by this method, the prefix defined in this map is used.

Returns:

a map with [namespace, schema prefix] pairs that should be included in each document encoded with the given context in addition to the pairs from getNamespacePrefixes().

getSchemaLocations

public static Map<String,String> getSchemaLocations(ILcdXMLDocumentContext aContext)

Returns a mapping between name space and schema location. These schema locations are encoded in the root element of all documents encoded with the given document context via the xsi:schemaLocations attribute. When a name space occurs both in getNamespacePrefixes() and in the map returned by this method, the schema location defined in this map is used.

Returns:

a map with [namespace, schema location] pairs that should be included in each document encoded with the given context in addition to the pairs from getSchemaLocations().

getNamespacePrefixes

public Map<String,String> getNamespacePrefixes()

Returns a map containing as keys the namespaces supported by this encoder, and as values their corresponding prefixes.

Returns:

a map with all [namespace, prefix] pairs that should be used in each document that is encoded.

registerNamespaceURI

public void registerNamespaceURI(String aNamespaceURI,
                                 String aPrefix,
                                 String aSchemaLocation)

Registers the specified namespace on this encoder. Namespaces should be registered to indicate that the XML Schema associated with the registered namespace is now supported by this encoder.

Parameters:

aNamespaceURI - the namespace of an XML Schema for which marshallers are registered on this encoder.

aPrefix - the preferred prefix to be used for encoding elements in the specified namespace. If aPrefix was already registered for another namespace, or aPrefix == null, the encoder will choose another prefix itself.

aSchemaLocation - a location where the schema for the specified namespace can be found. This location will be encoded in the root element of all documents encoded by this encoder via the xsi:schemaLocations attribute.

configure

public void configure(TLcdDataModel aDataModel)

Configures this encoder for the given data model and all its dependencies. Configuration is done using all ILcdXMLSchemaBasedEncoderLibrary instances that are annotated (see TLcdXMLSchemaMappingAnnotation) on the given data model and its dependencies.

Note that creating a new encoder and configuring it with a data model is equivalent to creating an encoder with the encoder libraries of the data model and all its dependencies as constructor parameters.

Parameters:

aDataModel - the data model for which this encoder is to be configured