- All Implemented Interfaces:
Unmarshaller
Unmarshaller
implementation.
This class provides a partial default implementation for the
Unmarshaller
interface.
A Jakarta XML Binding Provider has to implement five methods getUnmarshallerHandler(), unmarshal(Node), unmarshal(XMLReader,InputSource), unmarshal(XMLStreamReader), and unmarshal(XMLEventReader).
- Author:
- Kohsuke Kawaguchi, Sun Microsystems, Inc.
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from interface jakarta.xml.bind.Unmarshaller
Unmarshaller.Listener
-
Constructor Summary
ModifierConstructorDescriptionprotected
Do-nothing constructor for the derived classes. -
Method Summary
Modifier and TypeMethodDescriptionprotected UnmarshalException
Creates an UnmarshalException from a SAXException.<A extends XmlAdapter<?,
?>>
AgetAdapter
(Class<A> type) Gets the adapter associated with the specified type.Return the current event handler or the default event handler if one hasn't been set.ReturnUnmarshaller.Listener
registered with thisUnmarshaller
.getProperty
(String name) Default implementation of the getProperty method always throws PropertyException since there are no required properties.Get the JAXPSchema
object being used to perform unmarshal-time validation.protected XMLReader
Obtains a configured XMLReader.<A extends XmlAdapter<?,
?>>
voidsetAdapter
(A adapter) Associates a configured instance ofXmlAdapter
with this unmarshaller.<A extends XmlAdapter<?,
?>>
voidsetAdapter
(Class<A> type, A adapter) Associates a configured instance ofXmlAdapter
with this unmarshaller.void
Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.void
setEventHandler
(ValidationEventHandler handler) Allow an application to register a validation event handler.void
setListener
(Unmarshaller.Listener listener) Register unmarshal event callbackUnmarshaller.Listener
with thisUnmarshaller
.void
setProperty
(String name, Object value) Default implementation of the setProperty method always throws PropertyException since there are no required properties.void
Specify the JAXPSchema
object that should be used to validate subsequent unmarshal operations against.final Object
Unmarshal XML data from the specified file and return the resulting content tree.final Object
unmarshal
(InputStream is) Unmarshal XML data from the specified InputStream and return the resulting content tree.final Object
Unmarshal XML data from the specified Reader and return the resulting content tree.final Object
Unmarshal XML data from the specified URL and return the resulting content tree.unmarshal
(XMLEventReader reader) Unmarshal XML data from the specified pull parser and return the resulting content tree.<T> JAXBElement
<T> unmarshal
(XMLEventReader reader, Class<T> expectedType) Unmarshal root element to Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.unmarshal
(XMLStreamReader reader) Unmarshal XML data from the specified pull parser and return the resulting content tree.<T> JAXBElement
<T> unmarshal
(XMLStreamReader reader, Class<T> expectedType) Unmarshal root element to Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.Unmarshal XML data from the specified XML Source and return the resulting content tree.<T> JAXBElement
<T> Unmarshal XML data from the specified XML Source bydeclaredType
and return the resulting content tree.<T> JAXBElement
<T> Unmarshal XML data by Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.final Object
unmarshal
(InputSource source) Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.protected abstract Object
unmarshal
(XMLReader reader, InputSource source) Unmarshalls 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 jakarta.xml.bind.Unmarshaller
getUnmarshallerHandler, unmarshal
-
Constructor Details
-
AbstractUnmarshallerImpl
protected AbstractUnmarshallerImpl()Do-nothing constructor for the derived classes.
-
-
Method Details
-
getXMLReader
Obtains a configured XMLReader.This method is used when the client-specified
SAXSource
object doesn't have XMLReader.Unmarshaller
is not re-entrant, so we will only use one instance of XMLReader.- Throws:
JAXBException
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified XML Source and return the resulting content tree.Implements Unmarshal Global Root Element.
A client application can choose not to use the default parser mechanism supplied with their Jakarta XML Binding provider. Any SAX 2.0 compliant parser can be substituted for the Jakarta XML Binding provider's default mechanism. To do so, the client application must properly configure a
SAXSource
containing anXMLReader
implemented by the SAX 2.0 parser provider. If theXMLReader
has anorg.xml.sax.ErrorHandler
registered on it, it will be replaced by the Jakarta XML Binding Provider so that validation errors can be reported via theValidationEventHandler
mechanism of Jakarta XML Binding. If theSAXSource
does not contain anXMLReader
, then the Jakarta XML Binding provider's default parser mechanism will be used.This parser replacement mechanism can also be used to replace the Jakarta XML Binding 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 Jakarta XML Binding provider and converted into Jakarta XML BindingValidationEvent
objects which will be reported back to the client via theValidationEventHandler
registered with theUnmarshaller
. Note: specifying a substitute validating SAX 2.0 parser for unmarshalling does not necessarily replace the validation engine used by the Jakarta XML Binding 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 Jakarta XML Binding provider's default parser and validator mechanisms.- Specified by:
unmarshal
in interfaceUnmarshaller
- 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:
-
unmarshal
Unmarshalls an object by using the specified XMLReader and the InputSource.The callee should call the setErrorHandler method of the XMLReader so that errors are passed to the client-specified ValidationEventHandler.
- Throws:
JAXBException
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.Implements Unmarshal Global Root Element.
- Specified by:
unmarshal
in interfaceUnmarshaller
- 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
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified URL and return the resulting content tree.Implements Unmarshal Global Root Element.
- Specified by:
unmarshal
in interfaceUnmarshaller
- 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
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified file and return the resulting content tree.Implements Unmarshal Global Root Element.
- Specified by:
unmarshal
in interfaceUnmarshaller
- Parameters:
f
- 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
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified InputStream and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API.Implements Unmarshal Global Root Element.
- Specified by:
unmarshal
in interfaceUnmarshaller
- 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
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified Reader and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API, because a Reader does not provide the system ID.Implements Unmarshal Global Root Element.
- Specified by:
unmarshal
in interfaceUnmarshaller
- Parameters:
reader
- the Reader 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
-
setEventHandler
Allow an application to register a validation event handler.The validation event handler will be called by the Jakarta XML Binding 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.- Specified by:
setEventHandler
in interfaceUnmarshaller
- Parameters:
handler
- the validation event handler- Throws:
JAXBException
- if an error was encountered while setting the event handler
-
getEventHandler
Return the current event handler or the default event handler if one hasn't been set.- Specified by:
getEventHandler
in interfaceUnmarshaller
- Returns:
- the current ValidationEventHandler or the default event handler if it hasn't been set
- Throws:
JAXBException
- if an error was encountered while getting the current event handler
-
createUnmarshalException
Creates an UnmarshalException from a SAXException.This is a utility method provided for the derived classes.
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 to SAXException and reduce those excessive wrapping.
- Returns:
- the resulting UnmarshalException
-
setProperty
Default implementation of the setProperty method always throws PropertyException since there are no required properties. If a provider needs to handle additional properties, it should override this method in a derived class.- Specified by:
setProperty
in interfaceUnmarshaller
- Parameters:
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- Throws:
PropertyException
- when there is an error processing the given property or value
-
getProperty
Default implementation of the getProperty method always throws PropertyException since there are no required properties. If a provider needs to handle additional properties, it should override this method in a derived class.- Specified by:
getProperty
in interfaceUnmarshaller
- Parameters:
name
- the name of the property to retrieve- Returns:
- the value of the requested property
- Throws:
PropertyException
- when there is an error retrieving the given property or value property name
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified pull parser and return the resulting content tree.This method is an Unmarshal Global Root method.
This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the
reader
will be pointing at the token right after the end event.- Specified by:
unmarshal
in interfaceUnmarshaller
- Parameters:
reader
- The parser to be read.- Returns:
- the newly created root object of the java content tree.
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling- See Also:
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified pull parser and return the resulting content tree.Implements Unmarshal Global Root Element.
This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the
reader
will be pointing at the token right after the end event.- Specified by:
unmarshal
in interfaceUnmarshaller
- Parameters:
reader
- The parser to be read.- Returns:
- the newly created root object of the java content tree.
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling- See Also:
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data by Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.Implements Unmarshal by Declared Type
- Specified by:
unmarshal
in interfaceUnmarshaller
- Type Parameters:
T
- the XML Binding mapped class- Parameters:
node
- the document/element to unmarshal XML data from. The caller must support at least Document and Element.expectedType
- appropriate Jakarta XML Binding mapped class to holdnode
's XML data.- Returns:
- JAXBElement representation of
node
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling
-
unmarshal
Description copied from interface:Unmarshaller
Unmarshal XML data from the specified XML Source bydeclaredType
and return the resulting content tree.Implements Unmarshal by Declared Type
- Specified by:
unmarshal
in interfaceUnmarshaller
- Type Parameters:
T
- the XML Binding mapped class- Parameters:
source
- the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)expectedType
- appropriate Jakarta XML Binding mapped class to holdsource
's xml root element- Returns:
- Java content rooted by JAXBElement
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling
-
unmarshal
public <T> JAXBElement<T> unmarshal(XMLStreamReader reader, Class<T> expectedType) throws JAXBException Description copied from interface:Unmarshaller
Unmarshal root element to Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.This method implements unmarshal by declaredType.
This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the
reader
will be pointing at the token right after the end event.- Specified by:
unmarshal
in interfaceUnmarshaller
- Type Parameters:
T
- the XML Binding mapped class- Parameters:
reader
- The parser to be read.expectedType
- appropriate Jakarta XML Binding mapped class to holdreader
's START_ELEMENT XML data.- Returns:
- content tree rooted by JAXBElement representation
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling
-
unmarshal
public <T> JAXBElement<T> unmarshal(XMLEventReader reader, Class<T> expectedType) throws JAXBException Description copied from interface:Unmarshaller
Unmarshal root element to Jakarta XML Binding mappeddeclaredType
and return the resulting content tree.This method implements unmarshal by declaredType.
This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the
reader
will be pointing at the token right after the end event.- Specified by:
unmarshal
in interfaceUnmarshaller
- Type Parameters:
T
- the XML Binding mapped class- Parameters:
reader
- The parser to be read.expectedType
- appropriate Jakarta XML Binding mapped class to holdreader
's START_ELEMENT XML data.- Returns:
- content tree rooted by JAXBElement representation
- Throws:
JAXBException
- If any unexpected errors occur while unmarshalling
-
setSchema
Description copied from interface:Unmarshaller
Specify the JAXPSchema
object that should be used to validate subsequent unmarshal operations against. Passing null into this method will disable validation.Initially this property is set to
null
.- Specified by:
setSchema
in interfaceUnmarshaller
- Parameters:
schema
- Schema object to validate unmarshal operations against or null to disable validation
-
getSchema
Description copied from interface:Unmarshaller
Get the JAXPSchema
object being used to perform unmarshal-time validation. If there is no Schema set on the unmarshaller, then this method will return null indicating that unmarshal-time validation will not be performed.- Specified by:
getSchema
in interfaceUnmarshaller
- Returns:
- the Schema object being used to perform unmarshal-time validation or null if not present
-
setAdapter
Description copied from interface:Unmarshaller
Associates a configured instance ofXmlAdapter
with this unmarshaller.This is a convenience method that invokes
setAdapter(adapter.getClass(),adapter);
.- Specified by:
setAdapter
in interfaceUnmarshaller
- Type Parameters:
A
- the type ofXmlAdapter
- Parameters:
adapter
- the configured instance ofXmlAdapter
- See Also:
-
setAdapter
Description copied from interface:Unmarshaller
Associates a configured instance ofXmlAdapter
with this unmarshaller.Every unmarshaller internally maintains a
Map
<Class
,XmlAdapter
>, which it uses for unmarshalling classes whose fields/methods are annotated withXmlJavaTypeAdapter
.This method allows applications to use a configured instance of
XmlAdapter
. When an instance of an adapter is not given, an unmarshaller will create one by invoking its default constructor.- Specified by:
setAdapter
in interfaceUnmarshaller
- Type Parameters:
A
- the type of the adapter- Parameters:
type
- The type of the adapter. The specified instance will be used whenXmlJavaTypeAdapter.value()
refers to this type.adapter
- The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.
-
getAdapter
Description copied from interface:Unmarshaller
Gets the adapter associated with the specified type. This is the reverse operation of theUnmarshaller.setAdapter(A)
method.- Specified by:
getAdapter
in interfaceUnmarshaller
- Type Parameters:
A
- the type of the adapter- Parameters:
type
- The type of the adapter. The specified instance will be used whenXmlJavaTypeAdapter.value()
refers to this type.- Returns:
- The adapter associated with the specified type.
-
setAttachmentUnmarshaller
Description copied from interface:Unmarshaller
Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments. Unmarshal time validation, enabled viaUnmarshaller.setSchema(Schema)
, must be supported even when unmarshaller is performing XOP processing.- Specified by:
setAttachmentUnmarshaller
in interfaceUnmarshaller
- Parameters:
au
- the attachment unmarshaller to be set
-
getAttachmentUnmarshaller
- Specified by:
getAttachmentUnmarshaller
in interfaceUnmarshaller
-
setListener
Description copied from interface:Unmarshaller
Register unmarshal event callback
Unmarshaller.Listener
with thisUnmarshaller
.There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to
null
.- Specified by:
setListener
in interfaceUnmarshaller
- Parameters:
listener
- provides unmarshal event callbacks for thisUnmarshaller
-
getListener
Description copied from interface:Unmarshaller
Return
Unmarshaller.Listener
registered with thisUnmarshaller
.- Specified by:
getListener
in interfaceUnmarshaller
- Returns:
- registered
Unmarshaller.Listener
ornull
if no Listener is registered with this Unmarshaller.
-