Package com.luciad.format.xml.bind.schema

Class 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 Details

    • 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 Details

    • 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