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

Class TLcdXMLSchemaBasedDecoder

java.lang.Object
com.luciad.format.xml.bind.schema.TLcdXMLSchemaBasedDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable
public class TLcdXMLSchemaBasedDecoder extends Object implements ILcdInputStreamFactoryCapable
Decoder for decoding an XML Schema-based XML document into a Java object graph, using ILcdXMLUnmarshaller's and ILcdXMLTypeUnmarshaller's.

The decoded Java object graph can be any valid Java object: the exact mapping between XML data and Java objects is fully customizable and depends on how the ILcdXMLUnmarshaller's and ILcdXMLTypeUnmarshaller are implemented. It can be anything from a tree-like structure which is very close to the original XML data structure (like a JDOM tree), to a completely different data structure, for example an ILcdModel with ILcdShape objects.

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

  • It has an additional provider for ILcdXMLTypeUnmarshaller's.
  • It has an additional schema mapping, providing type object factories and schema information.

Typical use if the data model is not known up front, or if it can contain unknown extensions: 


  TLcdXMLEntityResolver entityResolver = new TLcdXMLEntityResolver();
  // To avoid downloading schemas over the internet, add known schemas here. Other schemas will be downloaded when needed.
  entityResolver.registerEntity("http://mydomain/myschemanamespace", "/location/to/myschema.xsd");

  TLcdXMLSchemaBasedMapping mapping = new TLcdXMLSchemaBasedMapping();
  mapping.setDefaultEntityResolver(entityResolver);
  TLcdXMLDataObjectSchemaHandler schemaHandler = new TLcdXMLDataObjectSchemaHandler();

  TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(schemaHandler, mapping);
  schemaHandler.setDecoder(decoder);
  // The decoder is now ready to be used.

Typical use if the schema based data model is known up front (e.g. generated by TLcdXMLDataModelBuilder): 


   // Create a data model that represents your XML file's schema.
   TLcdXMLDataModelBuilder xmlDataModelBuilder = new TLcdXMLDataModelBuilder();
   TLcdDataModel myXMLDataModel = xmlDataModelBuilder.createDataModel(
     "http://mydomain/myschemanamespace", "location/to/myschema.xsd");

   TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder();
   decoder.configure(myXMLDataModel);
   // The decoder is now ready to be used.
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

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder()
      Creates a new, empty XML decoder.

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
      Creates a new XML decoder using the given schema handler and mapping.
      Parameters:
      aSchemaHandler - a handler for processing schemas, may be null.
      aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary, ILcdXMLSchemaHandler aSchemaHandler)
      Creates a decoder for the specified decoder library.

      This is a convenience constructor, being identical to: 

      
   TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, null);
   aLibrary.configureDecoder(decoder);
      Parameters:
      aLibrary - the decoder library for which to create a decoder.
      aSchemaHandler - a handler for processing schemas, may be null.

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries, ILcdXMLSchemaHandler aSchemaHandler)
      Creates a decoder for the specified decoder libraries.

      This is a convenience constructor, being identical to: 

      
   TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, null);
   for ( ILcdXMLSchemaBasedDecoderLibrary library : aLibraries ) {
     library.configureDecoder(decoder);
   }
      Parameters:
      aLibraries - the decoder libraries for which to create a decoder.
      aSchemaHandler - a handler for processing schemas, may be null.

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary, ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
      Creates a decoder for the specified decoder library.

      This is a convenience constructor, being identical to: 

      
   TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, aMapping);
   aLibrary.configureDecoder(decoder);
      Parameters:
      aLibrary - the decoder library for which to create a decoder.
      aSchemaHandler - a handler for processing schemas, may be null.
      aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

    • TLcdXMLSchemaBasedDecoder

      public TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries, ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
      Creates a decoder for the specified unmarshaller libraries.

      This is a convenience constructor, being identical to: 

      
   TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, aMapping);
   for ( ILcdXMLSchemaBasedDecoderLibrary library : aLibraries ) {
     library.configureDecoder(decoder);
   }
      Parameters:
      aLibraries - the decoder libraries for which to create a decoder.
      aSchemaHandler - a handler for processing schemas, may be null.
      aMapping - the schema mapping to be associated with this encoder. If null, this encoder will create an empty mapping itself.

  • Method Details

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Returns the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams.
      See Also:

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams. The input stream factory of the mapping associated with this decoder is also set to the given factory.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams.
      See Also:

    • getXMLInputFactory

      public XMLInputFactory getXMLInputFactory()
      Returns the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
      Returns:
      the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

    • setXMLInputFactory

      public void setXMLInputFactory(XMLInputFactory aXMLInputFactory)
      Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
      Parameters:
      aXMLInputFactory - the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

    • createDocumentContext

      public ILcdXMLDocumentContext createDocumentContext()
      Creates a new ILcdXMLDocumentContext that can be used during decoding of an XML document. A document context may only be used for decoding a single XML document and should be discarded afterwards.
      Returns:
      a new ILcdXMLDocumentContext that can be used during decoding of an XML document.

    • decode

      public Object decode(String aSourceName) throws XMLStreamException, IOException
      Unmarshals the specified document to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(String aSourceName, Class<T> aClass) throws XMLStreamException, IOException
      Unmarshals the specified document to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL.
      aClass - the expected class of the return value
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(String aSourceName, List<Class> aClasses) throws XMLStreamException, IOException
      Unmarshals the specified document to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL.
      aClasses - a list of classes which are allowed as return values. The decoder will give preference to the classes in the order they are sorted in the class list.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(String aSourceName, ILcdXMLDocumentContext aContext) throws XMLStreamException, IOException
      Unmarshals the specified document to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL.
      aContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(String aSourceName, InputStream aInputStream) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      aRootJavaClass - the class of the root Object in the returned Java object graph.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(String aSourceName, InputStream aInputStream, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(Source aSource, Class<T> aClass, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified source to a Java object graph.
      Parameters:
      aSource - the source from which the data should be read.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(Source aSource, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified source to a Java object graph.
      Parameters:
      aSource - the source from which the data should be read.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public Object decode(Source aSource) throws XMLStreamException, IOException
      Unmarshals the specified source to a Java object graph.
      Parameters:
      aSource - the source from which the data should be read.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(String aSourceName, InputStream aInputStream, List<Class> aJavaClasses) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      aJavaClasses - a list of classes which are allowed as return values. The decoder will give preference to the classes in the order they are sorted in the class list.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      aRootJavaClass - the class of the root Object in the returned Java object graph.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(String aSourceName, InputStream aInputStream, List<Class> aJavaClasses, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified input stream to a Java object graph.
      Parameters:
      aSourceName - the data source from which the data should be read; typically a file name or a URL. This should be the same as the source name of the input stream.
      aInputStream - the InputStream containing XML data to be unmarshalled.
      aJavaClasses - a list of classes which are allowed as return values. The decoder will give preference to the classes in the order they are sorted in the class list.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.

    • decode

      public <T> T decode(Source aSource, List<Class> aJavaClasses, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
      Unmarshals the specified source to a Java object graph.
      Parameters:
      aSource - the source from which the data should be read.
      aJavaClasses - a list of classes which are allowed as return values. The decoder will give preference to the classes in the order they are sorted in the class list.
      aDocumentContext - the document context to be used during unmarshalling.
      Returns:
      the unmarshalled Java object graph.
      Throws:
      XMLStreamException - if an unexpected processing exception occurs during unmarshalling.
      IOException - if an java.io.IOException occurs during unmarshalling.
      Since:
      2017.0

    • getUnmarshallerProvider

      public TLcdXMLSchemaBasedUnmarshallerProvider getUnmarshallerProvider()
      Returns the unmarshaller provider for this decoder, containing unmarshallers for converting XML data into Java object graphs.
      Returns:
      the unmarshaller provider for this decoder.

    • getTypeUnmarshallerProvider

      public TLcdXMLTypeUnmarshallerProvider getTypeUnmarshallerProvider()
      Returns the schema type unmarshaller provider for this decoder, containing schema type unmarshallers for converting Java object graphs to XML data.
      Returns:
      the schema type unmarshaller provider for this decoder.

    • getNamespaceURIs

      public Set<String> getNamespaceURIs()
      Returns the set of namespaces which are supported by this decoder.
      Returns:
      the set of namespaces which are supported by this decoder.

    • registerNamespaceURI

      public void registerNamespaceURI(String aNamespaceURI)
      Registers the specified namespace on this decoder. Namespaces should be registered to indicate that they are supported by this decoder.
      Parameters:
      aNamespaceURI - the namespace for which unmarshallers are registered on this decoder.

    • getMapping

      public TLcdXMLSchemaBasedMapping getMapping()
      Returns the TLcdXMLSchemaMapping associated with this decoder. This mapping is used by the decoder to retrieve schema information and object factories.
      Returns:
      the TLcdXMLSchemaMapping associated with this decoder.

    • configure

      public void configure(TLcdDataModel aDataModel)

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

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

      Parameters:
      aDataModel - the data model for which this decoder is to be configured