de.ispsoft.jaxme.jaxb
Class UnmarshallerImpl

java.lang.Object
  de.ispsoft.jaxme.jaxb.JMManagerFactoryAttachable
      de.ispsoft.jaxme.jaxb.UnmarshallerImpl

All Implemented Interfaces:

Unmarshaller

public class UnmarshallerImpl

extends JMManagerFactoryAttachable

implements Unmarshaller

Version:

$Id: UnmarshallerImpl.java,v 1.8 2003/07/03 23:20:25 joe Exp $

Author:

Jochen Wiedmann

Field Summary

Fields inherited from class de.ispsoft.jaxme.jaxb.JMManagerFactoryAttachable

BUILTIN_DATE_FORMAT, BUILTIN_DATETIME_FORMAT, BUILTIN_ENCODING, BUILTIN_TIME_FORMAT

Constructor Summary

UnmarshallerImpl()
Constructor for UnmarshallerImpl.

Method Summary

ValidationEventHandler	getEventHandler() Return the current event handler or the default event handler if one hasn't been set.
javax.xml.parsers.SAXParser	getSAXParser() Returns the SAXParser previously set with setSAXParser() or a new SAXParser.
javax.xml.parsers.SAXParserFactory	getSAXParserFactory() Returns the SAXParser factory.
UnmarshallerHandler	getUnmarshallerHandler() Get an unmarshaller handler object that can be used as a component in an XML pipeline.
org.xml.sax.XMLReader	getXMLReader()
boolean	isValidating() Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.
void	setEventHandler(ValidationEventHandler pHandler) Allow an application to register a ValidationEventHandler.
void	setValidating(boolean pValidating) Specifies whether or not the Unmarshaller should validate during unmarshal operations.
java.lang.Object	unmarshal(java.io.File pFile) Unmarshal XML data from the specified file and return the resulting content tree.
java.lang.Object	unmarshal(org.xml.sax.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(org.w3c.dom.Node pNode) Unmarshal XML data from the specified DOM tree and return the resulting content tree.
java.lang.Object	unmarshal(javax.xml.transform.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.

Methods inherited from class de.ispsoft.jaxme.jaxb.JMManagerFactoryAttachable

getDateFormat, getDateFormat, getDateFormatForPattern, getDateTimeFormat, getDateTimeFormat, getEncoding, getFactory, getLocale, getMessageFormat, getNumberFormat, getPrivateProperty, getProperty, getResourceBundle, getResourceValue, getTimeFormat, getTimeFormat, setDateFormat, setDateTimeFormat, setEncoding, setFactory, setLocale, setPrivateProperty, setProperty, setResourceBundle, setTimeFormat

Methods inherited from class java.lang.Object

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

Constructor Detail

UnmarshallerImpl

public UnmarshallerImpl()

Constructor for UnmarshallerImpl.

Method Detail

unmarshal

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

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified file and return the resulting content tree.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

pFile - the file to unmarshal XML data from

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(File)

unmarshal

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

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified InputStream and return the resulting content tree.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

is - the InputStream to unmarshal XML data from

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(InputStream)

unmarshal

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

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified URL and return the resulting content tree.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

url - the url to unmarshal XML data from

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(URL)

unmarshal

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

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

source - the input source to unmarshal XML data from

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(InputSource)

unmarshal

public java.lang.Object unmarshal(org.w3c.dom.Node pNode)
                           throws JAXBException

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified DOM tree and return the resulting content tree.

Specified by:

unmarshal in interface Unmarshaller

Parameters:

pNode - the document/element to unmarshal XML data from. The caller must support at least Document and Element.

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(Node)

unmarshal

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

Description copied from interface: Unmarshaller

Unmarshal XML data from the specified XML Source and return the resulting content tree.

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

TODO: what if their XMLReader already has an ErrorHandler set? I'm currently clobbering it in the RI with our ErrorHandler that converts SAXParserExceptions into JAXB ValidationEvents.

TODO: include a matrix that shows which validator will be used based on the use of this api?

Specified by:

unmarshal in interface Unmarshaller

Parameters:

source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)

Returns:

the newly created root object of the java content tree

Throws:

JAXBException - If any unexpected errors occur while unmarshalling

See Also:

Unmarshaller.unmarshal(Source)

getSAXParserFactory

public javax.xml.parsers.SAXParserFactory getSAXParserFactory()

Returns the SAXParser factory. By default a static instance is returned.

getSAXParser

public javax.xml.parsers.SAXParser getSAXParser()
                                         throws JAXBException,
                                                org.xml.sax.SAXException

Returns the SAXParser previously set with setSAXParser() or a new SAXParser.

IMPLEMENTATION NOTE: If you never use setSAXParser() with a non-null value, then this method is thread safe, because it will never return the same SAXParser twice. If setSAXParser() is invoked with a non-null value, then there is a small chance, that this parser is returned twice.

Throws:

JAXBException

org.xml.sax.SAXException

getXMLReader

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

Throws:

JAXBException

getUnmarshallerHandler

public UnmarshallerHandler getUnmarshallerHandler()

Description copied from interface: Unmarshaller

Get an unmarshaller handler object that can be used as a component in an XML pipeline.

TODO: This method needs better documentation. It is not intended to be used by novice JAXB users - it is a more advanced feature available for clients wishing to integrate their JAXB unmarshal into an XML pipeline.

The JAXB Provider can return the same handler object for multiple invocations of this method. In other words, this method does not necessarily create a new instance of UnmarshallerHandler. If the application needs to use more than one UnmarshallerHandler, it should create more than one Unmarshaller.

Specified by:

getUnmarshallerHandler in interface Unmarshaller

Returns:

the unmarshaller handler object

See Also:

Unmarshaller.getUnmarshallerHandler()

setEventHandler

public void setEventHandler(ValidationEventHandler pHandler)

Description copied from interface: Unmarshaller

Allow an application to register a ValidationEventHandler.

The ValidationEventHandler 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 ValidationEventHandler before invoking the unmarshal methods, then ValidationEvents will be handled by the default event handler which will terminate the unmarshal operation after the first error or warning is encountered.

Specified by:

setEventHandler in interface Unmarshaller

Parameters:

pHandler - the validation event handler

getEventHandler

public ValidationEventHandler getEventHandler()

Description copied from interface: Unmarshaller

Return the current event handler or the default event handler if one hasn't been set.

Specified by:

getEventHandler in interface Unmarshaller

Returns:

the current ValidationEventHandler or the default event handler if it hasn't been set

setValidating

public void setValidating(boolean pValidating)

Description copied from interface: Unmarshaller

Specifies whether or not the Unmarshaller should validate during unmarshal operations. By default, the Unmarshaller does not validate.

This method may only be invoked before or after calling one of the unmarshal methods.

This method only controls the JAXB Provider's default unmarshal-time validation mechanism - it has no impact on clients that specify their own validating SAX 2.0 compliant parser. Clients that specify their own unmarshal-time validation mechanism may wish to turn off the JAXB Provider's default validation mechanism via this API to avoid "double validation".

Specified by:

setValidating in interface Unmarshaller

Parameters:

pValidating - true if the Unmarshaller should validate during unmarshal, false otherwise

isValidating

public boolean isValidating()

Description copied from interface: Unmarshaller

Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.

This API returns the state of the JAXB Provider's default unmarshal-time validation mechanism.

Note: I named this method isValidating() to stay in-line with JAXP, as opposed to naming it getValidating().

Specified by:

isValidating in interface Unmarshaller

Returns:

true if the Unmarshaller is configured to validate during unmarshal operations, false otherwise