Package com.luciad.format.xml.bind

Class TLcdXMLDecoder

java.lang.Object
com.luciad.format.xml.bind.TLcdXMLDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable
public class TLcdXMLDecoder extends Object implements ILcdInputStreamFactoryCapable
Main class for unmarshalling an XML document into a Java object graph, using ILcdXMLUnmarshaller'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 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 decoder will set up a new XMLStreamReader for each document to be unmarshalled, create a new document context, look up an unmarshaller for the root element of the document and delegate the unmarshalling process to this unmarshaller.

This class is thread-safe and can be shared among multiple threads.

Please refer to the package documentation for a general overview of the XML Binding Framework.

Since:
9.0

  • Constructor Details

    • TLcdXMLDecoder

      public TLcdXMLDecoder()
      Creates a new, empty TLcdXMLDecoder.

    • TLcdXMLDecoder

      public TLcdXMLDecoder(ILcdXMLDecoderLibrary aLibrary)
      Creates a new TLcdXMLDecoder for the specified decoder library.

      This is a convenience constructor, identical to: 

      
   TLcdXMLDecoder decoder = new TLcdXMLDecoder();
   aLibrary.configureDecoder(decoder);
      Parameters:
      aLibrary - the decoder library for which to create an XML decoder.

    • TLcdXMLDecoder

      public TLcdXMLDecoder(List<ILcdXMLDecoderLibrary> aLibraries)
      Creates a new TLcdXMLDecoder for the specified decoder libraries.

      This is a convenience constructor, being identical to: 

      
   TLcdXMLDecoder decoder = new TLcdXMLDecoder();
   for ( ILcdXMLDecoderLibrary library : aLibraries) {
     library.configureDecoder(decoder);
   }
      Parameters:
      aLibraries - the decoder libraries for which to create an XML decoder.

    • TLcdXMLDecoder

      public TLcdXMLDecoder(List<ILcdXMLDecoderLibrary> aLibraries, TLcdXMLMapping aMapping)

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

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the com.luciad.io.ILcdInputStreamFactory to be used by this decoder for creating input streams.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams.

    • 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 unmarshaller 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(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.

    • getUnmarshallerProvider

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

    • getNamespaceURIs

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

    • getMapping

      public TLcdXMLMapping getMapping()

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