public class TLcdXMLSchemaBasedDecoder extends Object implements ILcdInputStreamFactoryCapable
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:
ILcdXMLTypeUnmarshaller
's.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.Constructor and Description |
---|
TLcdXMLSchemaBasedDecoder()
Creates a new, empty XML decoder.
|
TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary,
ILcdXMLSchemaHandler aSchemaHandler)
Creates a decoder for the specified decoder library.
|
TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary,
ILcdXMLSchemaHandler aSchemaHandler,
TLcdXMLSchemaBasedMapping aMapping)
Creates a decoder for the specified decoder library.
|
TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaHandler aSchemaHandler,
TLcdXMLSchemaBasedMapping aMapping)
Creates a new XML decoder using the given schema handler and mapping.
|
TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries,
ILcdXMLSchemaHandler aSchemaHandler)
Creates a decoder for the specified decoder libraries.
|
TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries,
ILcdXMLSchemaHandler aSchemaHandler,
TLcdXMLSchemaBasedMapping aMapping)
Creates a decoder for the specified unmarshaller libraries.
|
Modifier and Type | Method and Description |
---|---|
void |
configure(TLcdDataModel aDataModel)
Configures this decoder for the given data model and all its
dependencies.
|
ILcdXMLDocumentContext |
createDocumentContext()
Creates a new
ILcdXMLDocumentContext that can be used during decoding of an XML
document. |
Object |
decode(Source aSource)
Unmarshals the specified source to a Java object graph.
|
<T> T |
decode(Source aSource,
Class<T> aClass,
ILcdXMLDocumentContext aDocumentContext)
Unmarshals the specified source to a Java object graph.
|
Object |
decode(Source aSource,
ILcdXMLDocumentContext aDocumentContext)
Unmarshals the specified source to a Java object graph.
|
<T> T |
decode(Source aSource,
List<Class> aJavaClasses,
ILcdXMLDocumentContext aDocumentContext)
Unmarshals the specified source to a Java object graph.
|
Object |
decode(String aSourceName)
Unmarshals the specified document to a Java object graph.
|
<T> T |
decode(String aSourceName,
Class<T> aClass)
Unmarshals the specified document to a Java object graph.
|
Object |
decode(String aSourceName,
ILcdXMLDocumentContext aContext)
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.
|
<T> T |
decode(String aSourceName,
InputStream aInputStream,
List<Class> aJavaClasses)
Unmarshals the specified input stream to a Java object graph.
|
<T> T |
decode(String aSourceName,
InputStream aInputStream,
List<Class> aJavaClasses,
ILcdXMLDocumentContext aDocumentContext)
Unmarshals the specified input stream to a Java object graph.
|
Object |
decode(String aSourceName,
List<Class> aClasses)
Unmarshals the specified document to a Java object graph.
|
ILcdInputStreamFactory |
getInputStreamFactory()
Returns the
com.luciad.io.ILcdInputStreamFactory that is used by this decoder for
creating input streams. |
TLcdXMLSchemaBasedMapping |
getMapping()
Returns the
TLcdXMLSchemaMapping associated with this decoder. |
Set<String> |
getNamespaceURIs()
Returns the set of namespaces which are supported by this decoder.
|
TLcdXMLTypeUnmarshallerProvider |
getTypeUnmarshallerProvider()
Returns the schema type unmarshaller provider for this decoder, containing schema
type unmarshallers for converting Java object graphs to XML data.
|
TLcdXMLSchemaBasedUnmarshallerProvider |
getUnmarshallerProvider()
Returns the unmarshaller provider for this 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 that is 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. |
public TLcdXMLSchemaBasedDecoder()
public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
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.public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary, ILcdXMLSchemaHandler aSchemaHandler)
TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, null);
aLibrary.configureDecoder(decoder);
aLibrary
- the decoder library for which to create a decoder.aSchemaHandler
- a handler for processing schemas, may be null
.public TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries, ILcdXMLSchemaHandler aSchemaHandler)
TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, null);
for ( ILcdXMLSchemaBasedDecoderLibrary library : aLibraries ) {
library.configureDecoder(decoder);
}
aLibraries
- the decoder libraries for which to create a decoder.aSchemaHandler
- a handler for processing schemas, may be null
.public TLcdXMLSchemaBasedDecoder(ILcdXMLSchemaBasedDecoderLibrary aLibrary, ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, aMapping);
aLibrary.configureDecoder(decoder);
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.public TLcdXMLSchemaBasedDecoder(List<ILcdXMLSchemaBasedDecoderLibrary> aLibraries, ILcdXMLSchemaHandler aSchemaHandler, TLcdXMLSchemaBasedMapping aMapping)
TLcdXMLSchemaBasedDecoder decoder = new TLcdXMLSchemaBasedDecoder(aSchemaHandler, aMapping);
for ( ILcdXMLSchemaBasedDecoderLibrary library : aLibraries ) {
library.configureDecoder(decoder);
}
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.public ILcdInputStreamFactory getInputStreamFactory()
com.luciad.io.ILcdInputStreamFactory
that is used by this decoder for
creating input streams.getInputStreamFactory
in interface ILcdInputStreamFactoryCapable
com.luciad.io.ILcdInputStreamFactory
that is used by this decoder for
creating input streams.setInputStreamFactory(ILcdInputStreamFactory)
public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
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.setInputStreamFactory
in interface ILcdInputStreamFactoryCapable
aInputStreamFactory
- the com.luciad.io.ILcdInputStreamFactory
that is used by this decoder for
creating input streams.getInputStreamFactory()
public XMLInputFactory getXMLInputFactory()
javax.xml.stream.XMLInputFactory
that is used by this decoder for creating
javax.xml.stream.XMLStreamReader
instances.javax.xml.stream.XMLInputFactory
that is used by this decoder for creating
javax.xml.stream.XMLStreamReader
instances.public void setXMLInputFactory(XMLInputFactory aXMLInputFactory)
javax.xml.stream.XMLInputFactory
to be used by this decoder for creating
javax.xml.stream.XMLStreamReader
instances.aXMLInputFactory
- the javax.xml.stream.XMLInputFactory
to be used by this decoder
for creating javax.xml.stream.XMLStreamReader
instances.public ILcdXMLDocumentContext createDocumentContext()
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.ILcdXMLDocumentContext
that can be used during decoding of an XML
document.public Object decode(String aSourceName) throws XMLStreamException, IOException
aSourceName
- the data source from which the data should be read; typically a file name or a URL.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(String aSourceName, Class<T> aClass) throws XMLStreamException, IOException
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 valueXMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(String aSourceName, List<Class> aClasses) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(String aSourceName, ILcdXMLDocumentContext aContext) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(String aSourceName, InputStream aInputStream) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(String aSourceName, InputStream aInputStream, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(Source aSource, Class<T> aClass, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
aSource
- the source from which the data should be read.aDocumentContext
- the document context to be used during unmarshalling.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(Source aSource, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
aSource
- the source from which the data should be read.aDocumentContext
- the document context to be used during unmarshalling.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public Object decode(Source aSource) throws XMLStreamException, IOException
aSource
- the source from which the data should be read.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(String aSourceName, InputStream aInputStream, List<Class> aJavaClasses) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(String aSourceName, InputStream aInputStream, Class<T> aRootJavaClass, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(String aSourceName, InputStream aInputStream, List<Class> aJavaClasses, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public <T> T decode(Source aSource, List<Class> aJavaClasses, ILcdXMLDocumentContext aDocumentContext) throws XMLStreamException, IOException
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.XMLStreamException
- if an unexpected processing exception occurs during unmarshalling.IOException
- if an java.io.IOException
occurs during unmarshalling.public TLcdXMLSchemaBasedUnmarshallerProvider getUnmarshallerProvider()
public TLcdXMLTypeUnmarshallerProvider getTypeUnmarshallerProvider()
public Set<String> getNamespaceURIs()
public void registerNamespaceURI(String aNamespaceURI)
aNamespaceURI
- the namespace for which unmarshallers are registered on
this decoder.public TLcdXMLSchemaBasedMapping getMapping()
TLcdXMLSchemaMapping
associated with this decoder. This mapping
is used by the decoder to retrieve schema information and object factories.TLcdXMLSchemaMapping
associated with this decoder.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.
aDataModel
- the data model for which this decoder is to be configured