|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.xml.bind.helpers.AbstractUnmarshallerImpl
Partial default Unmarshaller implementation.
This class provides a partial default implementation for the
Unmarshaller
interface.
A JAXB Provider has to implement three methods (getUnmarshallerHandler, unmarshal(Node), and unmarshal(XMLReader,InputSource)
Unmarshaller
Constructor Summary | |
AbstractUnmarshallerImpl()
|
Method Summary | |
protected UnmarshalException |
createUnmarshalException(SAXException e)
Creates an UnmarshalException from a SAXException. |
ValidationEventHandler |
getEventHandler()
Return the current event handler or the default event handler if one hasn't been set. |
java.lang.Object |
getProperty(java.lang.String name)
Default implementation of the getProperty method always throws PropertyException since there are no required properties. |
protected XMLReader |
getXMLReader()
Obtains a configured XMLReader. |
boolean |
isValidating()
Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations. |
void |
setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler. |
void |
setProperty(java.lang.String name,
java.lang.Object value)
Default implementation of the setProperty method always throws PropertyException since there are no required properties. |
void |
setValidating(boolean validating)
Specifies whether or not the Unmarshaller should validate during unmarshal operations. |
java.lang.Object |
unmarshal(java.io.File f)
Unmarshal XML data from the specified file and return the resulting content tree. |
java.lang.Object |
unmarshal(InputSource source)
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree. |
java.lang.Object |
unmarshal(java.io.InputStream is)
Unmarshal XML data from the specified InputStream and return the resulting content tree. |
java.lang.Object |
unmarshal(Source source)
Unmarshal XML data from the specified XML Source and return the resulting content tree. |
java.lang.Object |
unmarshal(java.net.URL url)
Unmarshal XML data from the specified URL and return the resulting content tree. |
protected abstract java.lang.Object |
unmarshal(XMLReader reader,
InputSource source)
Unmarshals an object by using the specified XMLReader and the InputSource. |
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 |
public AbstractUnmarshallerImpl()
Method Detail |
protected XMLReader getXMLReader() throws JAXBException
SAXSource
object doesn't have XMLReader.
Unmarshaller
is not re-entrant, so we will
only use one instance of XMLReader.
JAXBException
public java.lang.Object unmarshal(Source source) throws JAXBException
Unmarshaller
SAX 2.0 Parser Pluggability
A client application can choose not to use the default parser mechanism supplied with their JAXB provider. Any SAX 2.0 compliant parser can be substituted for the JAXB provider's default mechanism. To do so, the client application must properly configure a SAXSource containing an XMLReader implemented by the SAX 2.0 parser provider. If the XMLReader has an org.xml.sax.ErrorHandler registered on it, it will be replaced by the JAXB Provider so that validation errors can be reported via the ValidationEventHandler mechanism of JAXB. If the SAXSource does not contain an XMLReader, then the JAXB provider's default parser mechanism will be used.
This parser replacement mechanism can also be used to replace the JAXB provider's unmarshal-time validation engine. The client application must properly configure their SAX 2.0 compliant parser to perform validation (as shown in the example above). Any SAXParserExceptions encountered by the parser during the unmarshal operation will be processed by the JAXB provider and converted into JAXB ValidationEvent objects which will be reported back to the client via the ValidationEventHandler registered with the Unmarshaller. Note: specifying a substitute validating SAX 2.0 parser for unmarshalling does not necessarily replace the validation engine used by the JAXB provider for performing on-demand validation.
The only way for a client application to specify an alternate parser mechanism to be used during unmarshal is via the unmarshal(SAXSource) API. All other forms of the unmarshal method (File, URL, Node, etc) will use the JAXB provider's default parser and validator mechanisms.
unmarshal
in interface Unmarshaller
source
- the XML Source to unmarshal XML data from (providers are
only required to support SAXSource, DOMSource, and StreamSource)
JAXBException
- If any unexpected errors occur while unmarshallingprotected abstract java.lang.Object unmarshal(XMLReader reader, InputSource source) throws JAXBException
JAXBException
public final java.lang.Object unmarshal(InputSource source) throws JAXBException
Unmarshaller
unmarshal
in interface Unmarshaller
source
- the input source to unmarshal XML data from
JAXBException
- If any unexpected errors occur while unmarshallingpublic final java.lang.Object unmarshal(java.net.URL url) throws JAXBException
Unmarshaller
unmarshal
in interface Unmarshaller
url
- the url to unmarshal XML data from
JAXBException
- If any unexpected errors occur while unmarshallingpublic final java.lang.Object unmarshal(java.io.File f) throws JAXBException
Unmarshaller
unmarshal
in interface Unmarshaller
f
- the file to unmarshal XML data from
JAXBException
- If any unexpected errors occur while unmarshallingpublic final java.lang.Object unmarshal(java.io.InputStream is) throws JAXBException
Unmarshaller
unmarshal
in interface Unmarshaller
is
- the InputStream to unmarshal XML data from
JAXBException
- If any unexpected errors occur while unmarshallingpublic boolean isValidating() throws JAXBException
Note: I named this method isValidating() to stay in-line with JAXP, as opposed to naming it getValidating().
isValidating
in interface Unmarshaller
JAXBException
- if an error occurs while retrieving the validating
flagpublic void setEventHandler(ValidationEventHandler handler) throws JAXBException
The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the unmarshal methods. If the client application does not register a validation event handler before invoking the unmarshal methods, then all validation events will be silently ignored and may result in unexpected behaviour.
setEventHandler
in interface Unmarshaller
handler
- the validation event handler
JAXBException
- if an error was encountered while setting the
event handlerpublic void setValidating(boolean validating) throws JAXBException
This method may only be invoked before or after calling one of the unmarshal methods.
setValidating
in interface Unmarshaller
validating
- true if the Unmarshaller should validate during
unmarshal, false otherwise
JAXBException
- if an error occurred while enabling or disabling
validation at unmarshal timepublic ValidationEventHandler getEventHandler() throws JAXBException
getEventHandler
in interface Unmarshaller
JAXBException
- if an error was encountered while getting the
current event handlerprotected UnmarshalException createUnmarshalException(SAXException e)
When a provider-implemented ContentHandler wants to throw a JAXBException, it needs to wrap the exception by a SAXException. If the unmarshaller implementation blindly wrap SAXException by JAXBException, such an exception will be a JAXBException wrapped by a SAXException wrapped by another JAXBException. This is silly.
This method checks the nested exception of SAXException and reduce those excessive wrapping.
public void setProperty(java.lang.String name, java.lang.Object value) throws PropertyException
setProperty
in interface Unmarshaller
name
- the name of the property to be set. This value can either
be specified using one of the constant fields or a user
supplied string.value
- the value of the property to be set
PropertyException
- when there is an error processing the given
property or valuepublic java.lang.Object getProperty(java.lang.String name) throws PropertyException
getProperty
in interface Unmarshaller
name
- the name of the property to retrieve
PropertyException
- when there is an error retrieving the given property or value
property name
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |