com.luciad.format.xml.bind

LuciadFusionClass 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 Summary

Constructors

Constructor and Description
TLcdXMLDecoder() Creates a new, empty TLcdXMLDecoder.
TLcdXMLDecoder(ILcdXMLDecoderLibrary aLibrary) Creates a new TLcdXMLDecoder for the specified decoder library.
TLcdXMLDecoder(List<ILcdXMLDecoderLibrary> aLibraries) Creates a new TLcdXMLDecoder for the specified decoder libraries.
TLcdXMLDecoder(List<ILcdXMLDecoderLibrary> aLibraries, TLcdXMLMapping aMapping)

Method Summary

Modifier and Type	Method and Description
ILcdXMLDocumentContext	createDocumentContext() Creates a new ILcdXMLDocumentContext that can be used during decoding of an XML document.
Object	decode(String aSourceName) Unmarshals the specified document to a Java object graph.
Object	decode(String aSourceName, InputStream aInputStream) Unmarshals the specified input stream to a Java object graph.
<T> T	decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass) Unmarshals the specified input stream to a Java object graph.
<T> T	decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass, ILcdXMLDocumentContext aDocumentContext) Unmarshals the specified input stream to a Java object graph.
Object	decode(String aSourceName, InputStream aInputStream, ILcdXMLDocumentContext aDocumentContext) Unmarshals the specified input stream to a Java object graph.
ILcdInputStreamFactory	getInputStreamFactory() Returns the com.luciad.io.ILcdInputStreamFactory that is used by this decoder for creating input streams.
TLcdXMLMapping	getMapping()
Set<String>	getNamespaceURIs() Returns the set of namespaces which are supported by this decoder.
TLcdXMLUnmarshallerProvider	getUnmarshallerProvider() Returns the unmarshaller provider for this XML decoder, containing unmarshallers for converting XML data into Java object graphs.
XMLInputFactory	getXMLInputFactory() Returns the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
void	registerNamespaceURI(String aNamespaceURI) Registers the specified namespace on this decoder.
void	setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory) Sets the com.luciad.io.ILcdInputStreamFactory to be used by this decoder for creating input streams.
void	setXMLInputFactory(XMLInputFactory aXMLInputFactory) Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

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.