javax.xml.bind
Interface Unmarshaller
- JMUnmarshaller
- AbstractUnmarshallerImpl, JMUnmarshallerImpl
public interface Unmarshaller
A
Unmarshaller
is the opposite of the
Marshaller
:
It takes as input XML in either of several representations (byte or
character stream, DOM node, or a series of SAX events) and returns
a JAXB object with the same contents.
If the JAXB user demands, the
Unmarshaller
may also
validate the content tree that it sees.
ValidationEventHandler | getEventHandler() - If the JAXB application has registered a custom handler
for validation events, returns that handler.
|
java.lang.Object | getProperty(String pName) - Returnss the unmarshaller property
pName to the value
pValue .
|
UnmarshallerHandler | getUnmarshallerHandler() - Returns a SAX 2
org.xml.sax.ContentHandler , which is
able to parse a SAX event stream and convert it into a JAXB
object.
|
boolean | isValidating() - Sets whether the
Unmarshaller is validating
the objects that it reads.
|
void | setEventHandler(ValidationEventHandler pHandler) - An application may customize the Unmarshallers behaviour
in case of validation problems by supplying a custom handler
for validation events.
|
void | setProperty(String pName, Object pValue) - Sets the unmarshaller property
pName to the value
pValue .
|
void | setValidating(boolean pValidating) - Sets whether the
Unmarshaller is validating
the objects that it reads.
|
java.lang.Object | unmarshal(InputSource pSource) - The Unmarshaller reads the byte stream or character
stream referred by the
org.xml.sax.InputSource
and converts it into an equivalent JAXB object.
|
java.lang.Object | unmarshal(Node pNode) - The Unmarshaller converts the given node into an equivalent
JAXB object.
|
java.lang.Object | unmarshal(Source pSource) - The Unmarshaller reads the XML representation from the given
Source and converts it into an equivalent JAXB object.
|
java.lang.Object | unmarshal(java.io.File pFile) - This method takes opens the given file
pFile
for input.
|
java.lang.Object | unmarshal(java.io.InputStream pStream) - The Unmarshaller reads the given byte stream
and converts it into an equivalent JAXB object.
|
java.lang.Object | unmarshal(java.net.URL pURL) - This method takes connects to the given
pURL
and opens a byte stream for input.
|
getEventHandler
public ValidationEventHandler getEventHandler()
throws JAXBException
If the JAXB application has registered a custom handler
for validation events, returns that handler. Otherwise returns
the default handler, which is triggering an exception in case
of errors and fatal errors.
getProperty
public java.lang.Object getProperty(String pName)
throws PropertyException
Returnss the unmarshaller property pName
to the value
pValue
. Note, that the value type depends on the
property being set.
pName
- The property name.
getUnmarshallerHandler
public UnmarshallerHandler getUnmarshallerHandler()
throws JAXBException
Returns a SAX 2
org.xml.sax.ContentHandler
, which is
able to parse a SAX event stream and convert it into a JAXB
object. This is particularly useful in a stack of SAX
handlers. (Think of Apache Cocoon.)
Note: The JAXB provider may choose to return the
same handler again, if the method is invoked more than once.
In other words, if you need to have multiple handlers (for
example, because you have multiple threads), then you should
create multiple
Unmarshallers
.
isValidating
public boolean isValidating()
throws JAXBException
Sets whether the Unmarshaller
is validating
the objects that it reads. The default is false.
- True, if the
Unmarshaller
is validating the objects
that it reads, false otherwise.
setEventHandler
public void setEventHandler(ValidationEventHandler pHandler)
throws JAXBException
An application may customize the Unmarshallers behaviour
in case of validation problems by supplying a custom handler
for validation events. The default handler will trigger an
exception in case of errors and fatal errors.
pHandler
- The custom event handler or null to restore
the default event handler.
setProperty
public void setProperty(String pName,
Object pValue)
throws PropertyException
Sets the unmarshaller property pName
to the value
pValue
. Note, that the value type depends on the
property being set.
pName
- The property name.
setValidating
public void setValidating(boolean pValidating)
throws JAXBException
Sets whether the
Unmarshaller
is validating
the objects that it reads. The default is false.
Note: A validating unmarshaller will rarely use
a validating SAX parser by default! It does so, because the
SAX parsers validation and the Unmarshallers builtin
validation would most probably validate the same things,
resulting in no additional safety at the cost of wasting
performance. Second, a SAX parser is not always in use.
For example, you do not need a parser when
converting a DOM Node. If you insist in a validating XML
parser, then you should create your own
org.xml.sax.XMLReader
and use the method
unmarshal(javax.xml.transform.Source)
.
pValidating
- Whether the Unmarshaller
should validate
or not.
unmarshal
public java.lang.Object unmarshal(InputSource pSource)
throws JAXBException
The Unmarshaller reads the byte stream or character
stream referred by the org.xml.sax.InputSource
and converts it into an equivalent JAXB object.
pSource
- The InputSource
referring to a byte or
character stream. It is recommended, that the system ID is
set. This may be required, if the XML in the stream refers
to external entities.
- The JAXB object read from the byte or character stream.
JAXBException
- An unexpected problem (for example an
IOException) occurred.
unmarshal
public java.lang.Object unmarshal(Node pNode)
throws JAXBException
The Unmarshaller converts the given node into an equivalent
JAXB object.
pNode
- The node to convert. The JAXB provider must support
documents and elements. Other node types may not work
(document fragments) or cannot work (attributes, text nodes,
and so on).
- The JAXB object read from the DOM node.
unmarshal
public java.lang.Object unmarshal(Source pSource)
throws JAXBException
The Unmarshaller reads the XML representation from the given
Source
and converts it into an equivalent JAXB object.
The JAXB provider must support at least
javax.xml.transform.sax.SAXSource
,
javax.xml.transform.dom.DOMSource
, and
javax.xml.transform.stream.StreamSource
. A possible
implementation could validate whether the argument is actually
an instance of these subinterfaces. If so, it might simply
act like
getUnmarshallerHandler()
,
unmarshal(org.w3c.dom.Node)
,
unmarshal(InputStream)
, or
unmarshal(org.xml.sax.InputSource)
, respectively.
Note: If you are not using the standard JAXP
mechanism for obtaining an
org.xml.sax.XMLReader
,
then you might create your own SAX parser and invoke the
pSource
arguments
javax.xml.transform.sax.SAXSource.setXMLReader(org.xml.sax.XMLReader)
.
The JAXB provider will detect and use your SAX parser.
pSource
- The Source
being read.
- The JAXB object read from the DOM node.
unmarshal
public java.lang.Object unmarshal(java.io.File pFile)
throws JAXBException
This method takes opens the given file pFile
for input. The Unmarshaller reads the byte stream contained in
the file and converts it into an equivalent JAXB object.
pFile
- The file being read.
- The JAXB object read from the file.
JAXBException
- An unexpected problem (for example an
IOException) occurred.
unmarshal
public java.lang.Object unmarshal(java.io.InputStream pStream)
throws JAXBException
The Unmarshaller reads the given byte stream
and converts it into an equivalent JAXB object.
pStream
- The stream being read.
- The JAXB object read from the byte stream.
JAXBException
- An unexpected problem (for example an
IOException) occurred.
unmarshal
public java.lang.Object unmarshal(java.net.URL pURL)
throws JAXBException
This method takes connects to the given pURL
and opens a byte stream for input. The Unmarshaller reads the
byte stream and converts it into an equivalent JAXB object.
pURL
- The URL being read.
- The JAXB object read from the URL.
JAXBException
- An unexpected problem (for example an
IOException) occurred.