javax.xml.bind
public interface Unmarshaller
A Unmarshaller
is the opposite of the {@link 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.
Since: JAXB1.0
See Also: JAXBContext Marshaller Validator
Method Summary | |
---|---|
ValidationEventHandler | getEventHandler() If the JAXB application has registered a custom handler for validation events, returns that handler. |
Object | getProperty(String pName) Returnss the unmarshaller property |
UnmarshallerHandler | getUnmarshallerHandler() Returns a SAX 2 {@link 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 |
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 |
void | setValidating(boolean pValidating) Sets whether the |
Object | unmarshal(File pFile) This method takes opens the given file |
Object | unmarshal(InputStream pStream) The Unmarshaller reads the given byte stream and converts it into an equivalent JAXB object. |
Object | unmarshal(URL pURL) This method takes connects to the given |
Object | unmarshal(InputSource pSource) The Unmarshaller reads the byte stream or character stream referred by the {@link org.xml.sax.InputSource} and converts it into an equivalent JAXB object. |
Object | unmarshal(Node pNode) The Unmarshaller converts the given node into an equivalent JAXB object. |
Object | unmarshal(Source pSource) The Unmarshaller reads the XML representation from the given {@link Source} and converts it into an equivalent JAXB object. The JAXB provider must support at least {@link javax.xml.transform.sax.SAXSource}, {@link javax.xml.transform.dom.DOMSource}, and {@link javax.xml.transform.stream.StreamSource}. |
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.
Returnss the unmarshaller property pName
to the value
pValue
. Note, that the value type depends on the
property being set.
Parameters: pName The property name.
Throws: PropertyException An error occurred while processing the property. IllegalArgumentException The name parameter was null.
Returns a SAX 2 {@link 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
.
Sets whether the Unmarshaller
is validating
the objects that it reads. The default is false.
Returns: True, if the Unmarshaller
is validating the objects
that it reads, false otherwise.
Throws: JAXBException Fetching the property value failed.
See Also: Unmarshaller
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.
Parameters: pHandler The custom event handler or null to restore the default event handler.
Throws: JAXBException Setting the handler failed.
Sets the unmarshaller property pName
to the value
pValue
. Note, that the value type depends on the
property being set.
Parameters: pName The property name.
Throws: PropertyException An error occurred while processing the property. IllegalArgumentException The name parameter was null.
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 {@link org.xml.sax.XMLReader} and use the method {@link #unmarshal(javax.xml.transform.Source)}.
Parameters: pValidating Whether the Unmarshaller
should validate
or not.
Throws: JAXBException Setting the property failed.
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.
Parameters: pFile The file being read.
Returns: The JAXB object read from the file.
Throws: JAXBException An unexpected problem (for example an IOException) occurred. UnmarshalException The JAXB object is invalid or could not be read from the byte stream for similar reasons. IllegalArgumentException The parameter was null.
The Unmarshaller reads the given byte stream and converts it into an equivalent JAXB object.
Parameters: pStream The stream being read.
Returns: The JAXB object read from the byte stream.
Throws: JAXBException An unexpected problem (for example an IOException) occurred. UnmarshalException The JAXB object is invalid or could not be read from the byte stream for similar reasons. IllegalArgumentException The parameter was null.
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.
Parameters: pURL The URL being read.
Returns: The JAXB object read from the URL.
Throws: JAXBException An unexpected problem (for example an IOException) occurred. UnmarshalException The JAXB object is invalid or could not be read from the byte stream for similar reasons. IllegalArgumentException The parameter was null.
The Unmarshaller reads the byte stream or character stream referred by the {@link org.xml.sax.InputSource} and converts it into an equivalent JAXB object.
Parameters: pSource The {@link 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.
Returns: The JAXB object read from the byte or character stream.
Throws: JAXBException An unexpected problem (for example an IOException) occurred. UnmarshalException The JAXB object is invalid or could not be read from the byte stream for similar reasons. IllegalArgumentException The parameter was null.
The Unmarshaller converts the given node into an equivalent JAXB object.
Parameters: 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).
Returns: The JAXB object read from the DOM node.
Throws: JAXBException An unexpected problem occurred. UnmarshalException The JAXB object is invalid or could not be read for similar reasons. IllegalArgumentException The parameter was null.
The Unmarshaller reads the XML representation from the given {@link Source} and converts it into an equivalent JAXB object.
The JAXB provider must support at least {@link javax.xml.transform.sax.SAXSource}, {@link javax.xml.transform.dom.DOMSource}, and {@link 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 {@link #getUnmarshallerHandler()}, {@link #unmarshal(org.w3c.dom.Node)}, {@link #unmarshal(java.io.InputStream)}, or {@link #unmarshal(org.xml.sax.InputSource)}, respectively.
Note: If you are not using the standard JAXP
mechanism for obtaining an {@link org.xml.sax.XMLReader},
then you might create your own SAX parser and invoke the
pSource
arguments
{@link javax.xml.transform.sax.SAXSource#setXMLReader(org.xml.sax.XMLReader)}.
The JAXB provider will detect and use your SAX parser.
Parameters: pSource The {@link Source} being read.
Returns: The JAXB object read from the DOM node.
Throws: JAXBException An unexpected problem occurred. UnmarshalException The JAXB object is invalid or could not be read for similar reasons. IllegalArgumentException The parameter was null.