javax.xml.bind.helpers
Class AbstractUnmarshallerImpl

java.lang.Object
  javax.xml.bind.helpers.AbstractUnmarshallerImpl

All Implemented Interfaces:

Unmarshaller

public abstract class AbstractUnmarshallerImpl
extends java.lang.Object
implements Unmarshaller

This is an abstract default implementation of an Unmarshaller. Subclasses only need to implement Unmarshaller.getUnmarshallerHandler(), Unmarshaller.unmarshal(org.w3c.dom.Node), and unmarshal(org.xml.sax.XMLReader, org.xml.sax.InputSource).

Since:

JAXB1.0

Author:

JSR-31

Constructor Summary

AbstractUnmarshallerImpl()
Creates a new instance of AbstractUnmarshallerImpl.

Method Summary

protected UnmarshalException	createUnmarshalException(org.xml.sax.SAXException pException) Helper method to concert a SAXException into an UnmarshalException.
ValidationEventHandler	getEventHandler() If the JAXB application has registered a custom handler for validation events, returns that handler.
java.lang.Object	getProperty(java.lang.String pName) Always throws a PropertyException, because the default implementation does not support any properties.
protected org.xml.sax.XMLReader	getXMLReader() Creates a configured XMLReader.
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(java.lang.String pName, java.lang.Object pValue) Always throws a PropertyException, because the default implementation does not support any properties.
void	setValidating(boolean pValidating) Sets whether the Unmarshaller is validating the objects that it reads.
java.lang.Object	unmarshal(java.io.File pFile) This method takes opens the given file pFile for input.
java.lang.Object	unmarshal(org.xml.sax.InputSource pSource) The Unmarshaller reads the byte stream or character stream referred by the InputSource and converts it into an equivalent JAXB object.
java.lang.Object	unmarshal(java.io.InputStream pSource) The Unmarshaller reads the given byte stream and converts it into an equivalent JAXB object.
java.lang.Object	unmarshal(javax.xml.transform.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.net.URL pURL) This method takes connects to the given pURL and opens a byte stream for input.
protected abstract java.lang.Object	unmarshal(org.xml.sax.XMLReader pReader, org.xml.sax.InputSource pSource) Unmarshals an object by using the given instance of XMLReader to parse the XML document read from the byte or character stream given by the InputSource pSource.

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.xml.bind.Unmarshaller

getUnmarshallerHandler, unmarshal

Constructor Detail

AbstractUnmarshallerImpl

public AbstractUnmarshallerImpl()

Creates a new instance of AbstractUnmarshallerImpl.

Method Detail

getXMLReader

protected org.xml.sax.XMLReader getXMLReader()
                                      throws JAXBException

Creates a configured XMLReader. Unmarshaller is not re-entrant, so we will use a single instance of XMLReader.

Throws:

JAXBException - Encapsulates a ParserConfigurationException

unmarshal

public java.lang.Object unmarshal(javax.xml.transform.Source pSource)
                           throws JAXBException

Description copied from interface: Unmarshaller

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 SAXSource, DOMSource, and StreamSource. A possible implementation could validate whether the argument is actually an instance of these subinterfaces. If so, it might simply act like Unmarshaller.getUnmarshallerHandler(), Unmarshaller.unmarshal(org.w3c.dom.Node), Unmarshaller.unmarshal(java.io.InputStream), or Unmarshaller.unmarshal(org.xml.sax.InputSource), respectively.

Note: If you are not using the standard JAXP mechanism for obtaining an XMLReader, then you might create your own SAX parser and invoke the pSource arguments SAXSource.setXMLReader(org.xml.sax.XMLReader). The JAXB provider will detect and use your SAX parser.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

pSource - The 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.

unmarshal

protected abstract java.lang.Object unmarshal(org.xml.sax.XMLReader pReader,
                                              org.xml.sax.InputSource pSource)
                                       throws JAXBException

Unmarshals an object by using the given instance of XMLReader to parse the XML document read from the byte or character stream given by the InputSource pSource.

The implementation should call the method XMLReader.setErrorHandler(org.xml.sax.ErrorHandler) in order to pass errors provided by the SAX parser to the ValidationEventHandler provided by the client.

Throws:

JAXBException - An error occurred while unmarshalling the JAXB object.

unmarshal

public final java.lang.Object unmarshal(org.xml.sax.InputSource pSource)
                                 throws JAXBException

Description copied from interface: Unmarshaller

The Unmarshaller reads the byte stream or character stream referred by the InputSource and converts it into an equivalent JAXB object.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

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.

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.

unmarshal

public final java.lang.Object unmarshal(java.net.URL pURL)
                                 throws JAXBException

Description copied from interface: Unmarshaller

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.

Specified by:

unmarshal in interface Unmarshaller

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.

unmarshal

public final java.lang.Object unmarshal(java.io.File pFile)
                                 throws JAXBException

Description copied from interface: Unmarshaller

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.

Specified by:

unmarshal in interface Unmarshaller

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.

unmarshal

public final java.lang.Object unmarshal(java.io.InputStream pSource)
                                 throws JAXBException

Description copied from interface: Unmarshaller

The Unmarshaller reads the given byte stream and converts it into an equivalent JAXB object.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

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

isValidating

public boolean isValidating()
                     throws JAXBException

Description copied from interface: Unmarshaller

Sets whether the Unmarshaller is validating the objects that it reads. The default is false.

Specified by:

isValidating in interface Unmarshaller

Returns:

True, if the Unmarshaller is validating the objects that it reads, false otherwise.

Throws:

JAXBException - Fetching the property value failed.

See Also:

Unmarshaller.setValidating(boolean)

setValidating

public void setValidating(boolean pValidating)
                   throws JAXBException

Description copied from interface: Unmarshaller

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 XMLReader and use the method Unmarshaller.unmarshal(javax.xml.transform.Source).

Specified by:

setValidating in interface Unmarshaller

Parameters:

pValidating - Whether the Unmarshaller should validate or not.

Throws:

JAXBException - Setting the property failed.

getEventHandler

public ValidationEventHandler getEventHandler()
                                       throws JAXBException

Description copied from interface: Unmarshaller

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.

Specified by:

getEventHandler in interface Unmarshaller

Throws:

JAXBException

setEventHandler

public void setEventHandler(ValidationEventHandler pHandler)
                     throws JAXBException

Description copied from interface: 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.

Specified by:

setEventHandler in interface Unmarshaller

Parameters:

pHandler - The custom event handler or null to restore the default event handler.

Throws:

JAXBException - Setting the handler failed.

createUnmarshalException

protected UnmarshalException createUnmarshalException(org.xml.sax.SAXException pException)

Helper method to concert a SAXException into an UnmarshalException.

Parameters:

pException - If the parameter contains a nested instance of UnmarshalException, throws that instance. Otherwise wraps the parameter in a new UnmarshalException and throws that.

setProperty

public void setProperty(java.lang.String pName,
                        java.lang.Object pValue)
                 throws PropertyException

Always throws a PropertyException, because the default implementation does not support any properties. If you want to change this, override the class.

Specified by:

setProperty in interface Unmarshaller

Parameters:

pName - The property name.

Throws:

java.lang.IllegalArgumentException - The property name was null.

PropertyException - The name was not null. :-)

getProperty

public java.lang.Object getProperty(java.lang.String pName)
                             throws PropertyException

Always throws a PropertyException, because the default implementation does not support any properties. If you want to change this, override the class.

Specified by:

getProperty in interface Unmarshaller

Parameters:

pName - The property name.

Throws:

java.lang.IllegalArgumentException - The property name was null.

PropertyException - The name was not null. :-)