com.sun.xml.bind.v2.runtime.unmarshaller

Class UnmarshallingContext

java.lang.Object

com.sun.xml.bind.v2.runtime.Coordinator

com.sun.xml.bind.v2.runtime.unmarshaller.UnmarshallingContext

All Implemented Interfaces:

XmlVisitor, XmlVisitor.TextPredictor, ValidationEventHandler, NamespaceContext, ErrorHandler

public final class UnmarshallingContext
extends Coordinator
implements NamespaceContext, ValidationEventHandler, ErrorHandler, XmlVisitor, XmlVisitor.TextPredictor

Center of the unmarshalling.

This object is responsible for coordinating Loaders to perform the whole unmarshalling.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	UnmarshallingContext.State State information for each element.

Nested classes/interfaces inherited from interface com.sun.xml.bind.v2.runtime.unmarshaller.XmlVisitor

XmlVisitor.TextPredictor

Field Summary

Fields

Modifier and Type	Field and Description
ClassLoader	classLoader User-supplied ClassLoader for converting name to Class.
ClassResolver	classResolver Used to discover additional classes when we hit unknown elements/types.
UnmarshallerImpl	parent

Constructor Summary

Constructors

Constructor and Description
UnmarshallingContext(UnmarshallerImpl _parent, AssociationMap assoc) Creates a new unmarshaller.

Method Summary

Modifier and Type	Method and Description
void	addPatcher(Patcher job) Adds a job that will be executed at the last of the unmarshalling.
String	addToIdTable(String id) Adds the object which is currently being unmarshalled to the ID table.
void	clearStates()
Object	createInstance(Class<?> clazz) Creates a new instance of the specified class.
Object	createInstance(JaxBeanInfo beanInfo) Creates a new instance of the specified class.
void	endDocument()
void	endElement(TagName tagName)
void	endPrefixMapping(String prefix) Called after XmlVisitor.endElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify the end of a binding.
void	endScope(int frameSize) Ends the current packing scope.
void	errorUnresolvedIDREF(Object bean, String idref, LocatorEx loc) Called when there's no corresponding ID value.
boolean	expectText() Deprecated.
String[]	getAllDeclaredPrefixes() Returns a list of all in-scope prefixes.
UnmarshallingContext	getContext() Returns the UnmarshallingContext at the end of the chain.
Collection<QName>	getCurrentExpectedAttributes() Allows to access attributes which are expected in current state.
Collection<QName>	getCurrentExpectedElements() Allows to access elements which are expected in current state.
UnmarshallingContext.State	getCurrentState()
Object	getInnerPeer() Gets the inner peer JAXB object associated with the current element.
static UnmarshallingContext	getInstance() When called from within the realm of the unmarshaller, this method returns the current UnmarshallingContext in charge.
JAXBContextImpl	getJAXBContext()
protected ValidationEventLocator	getLocation() Gets the current location.
LocatorEx	getLocator() Gets the current source location information in SAX Locator.
String	getNamespaceURI(String prefix)
String[]	getNewlyDeclaredPrefixes() Returns a list of prefixes newly declared on the current element.
Callable	getObjectFromId(String id, Class targetType) Looks up the ID table and gets associated object.
Object	getOuterPeer() Gets the outer peer JAXB object associated with the current element.
XmlVisitor.TextPredictor	getPredictor() Deprecated.
String	getPrefix(String uri)
Iterator<String>	getPrefixes(String uri)
Object	getResult() Gets the result of the unmarshalling
Scope	getScope(int offset) Gets the currently active Scope.
StructureLoader	getStructureLoader() Gets StructureLoader if used as loader.
String	getXMIMEContentType() Gets the xmime:contentType value for the current object.
void	handleError(Exception e) Reports an exception found during the unmarshalling to the user.
void	handleError(Exception e, boolean canRecover)
void	handleError(String msg)
boolean	handleEvent(ValidationEvent event) Receive notification of a validation warning or error.
void	handleEvent(ValidationEvent event, boolean canRecover) Reports an error to the user, and asks if s/he wants to recover.
void	recordInnerPeer(Object innerPeer) Notifies the context about the inner peer of the current element.
void	recordOuterPeer(Object outerPeer) Notifies the context about the outer peer of the current element.
void	reset(InfosetScanner scanner, boolean isInplaceMode, JaxBeanInfo expectedType, IDResolver idResolver)
Loader	selectRootLoader(UnmarshallingContext.State state, TagName tag) On top of JAXBContextImpl#selectRootLoader(State, TagName), this method also consults ClassResolver.
void	setFactories(Object factoryInstances)
boolean	shouldErrorBeReported() Based on current Logger Level and errorCounter value determines if error should be reported.
void	startDocument(LocatorEx locator, NamespaceContext nsContext) Notifies a start of the document.
void	startElement(TagName tagName) Notifies a start tag of a new element.
void	startPrefixMapping(String prefix, String uri) Called before XmlVisitor.startElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify a new namespace binding.
void	startScope(int frameSize) Starts a new packing scope.
void	text(CharSequence pcdata) Text events.

Methods inherited from class com.sun.xml.bind.v2.runtime.Coordinator

_getInstance, containsAdapter, error, fatalError, getAdapter, popCoordinator, pushCoordinator, putAdapter, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xml.sax.ErrorHandler

error, fatalError, warning

Field Detail

parent

public final UnmarshallerImpl parent

classResolver

@Nullable
public ClassResolver classResolver

Used to discover additional classes when we hit unknown elements/types.

classLoader

@Nullable
public ClassLoader classLoader

User-supplied ClassLoader for converting name to Class. For backward compatibility, when null, use thread context classloader.

Constructor Detail

UnmarshallingContext

public UnmarshallingContext(UnmarshallerImpl _parent,
                            AssociationMap assoc)

Creates a new unmarshaller.

Parameters:

assoc - Must be both non-null when the unmarshaller does the in-place unmarshalling. Otherwise must be both null.

Method Detail

reset

public void reset(InfosetScanner scanner,
                  boolean isInplaceMode,
                  JaxBeanInfo expectedType,
                  IDResolver idResolver)

getJAXBContext

public JAXBContextImpl getJAXBContext()

getCurrentState

public UnmarshallingContext.State getCurrentState()

selectRootLoader

public Loader selectRootLoader(UnmarshallingContext.State state,
                               TagName tag)
                        throws SAXException

On top of JAXBContextImpl#selectRootLoader(State, TagName), this method also consults ClassResolver.

Throws:

SAXException - if ValidationEventHandler reported a failure.

clearStates

public void clearStates()

setFactories

public void setFactories(Object factoryInstances)

startDocument

public void startDocument(LocatorEx locator,
                          NamespaceContext nsContext)
                   throws SAXException

Description copied from interface: XmlVisitor

Notifies a start of the document.

Specified by:

startDocument in interface XmlVisitor

Parameters:

locator - This live object returns the location information as the parsing progresses. must not be null.

nsContext - Some broken XML APIs can't iterate all the in-scope namespace bindings, which makes it impossible to emulate XmlVisitor.startPrefixMapping(String, String) correctly when unmarshalling a subtree. Connectors that use such an API can pass in additional NamespaceContext object that knows about the in-scope namespace bindings. Otherwise (and normally) it is null.

Ideally this object should be immutable and only represent the namespace URI bindings in the context (those done above the element that JAXB started unmarshalling), but it can also work even if it changes as the parsing progress (to include namespaces declared on the current element being parsed.)

Throws:

SAXException

startElement

public void startElement(TagName tagName)
                  throws SAXException

Description copied from interface: XmlVisitor

Notifies a start tag of a new element. namespace URIs and local names must be interned.

Specified by:

startElement in interface XmlVisitor

Throws:

SAXException

text

public void text(CharSequence pcdata)
          throws SAXException

Description copied from interface: XmlVisitor

Text events.

The caller should consult XmlVisitor.TextPredictor to see if the unmarshaller is expecting any PCDATA. If the above is returning false, the caller is OK to skip any text in XML. The net effect is that we can ignore whitespaces quickly.

Specified by:

text in interface XmlVisitor

Parameters:

pcdata - represents character data. This object can be mutable (such as StringBuilder); it only needs to be fixed while this method is executing.

Throws:

SAXException

endElement

public final void endElement(TagName tagName)
                      throws SAXException

Specified by:

endElement in interface XmlVisitor

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

Specified by:

endDocument in interface XmlVisitor

Throws:

SAXException

expectText

@Deprecated
public boolean expectText()

Deprecated.

You should be always calling this through TextPredictor.

Specified by:

expectText in interface XmlVisitor.TextPredictor

getPredictor

@Deprecated
public XmlVisitor.TextPredictor getPredictor()

Deprecated.

You should be always getting TextPredictor from XmlVisitor.

Specified by:

getPredictor in interface XmlVisitor

getContext

public UnmarshallingContext getContext()

Description copied from interface: XmlVisitor

Returns the UnmarshallingContext at the end of the chain.

Specified by:

getContext in interface XmlVisitor

Returns:

always return the same object, so caching the result is recommended.

getResult

public Object getResult()
                 throws UnmarshalException

Gets the result of the unmarshalling

Throws:

UnmarshalException

createInstance

public Object createInstance(Class<?> clazz)
                      throws SAXException

Creates a new instance of the specified class. In the unmarshaller, we need to check the user-specified factory class.

Throws:

SAXException

createInstance

public Object createInstance(JaxBeanInfo beanInfo)
                      throws SAXException

Creates a new instance of the specified class. In the unmarshaller, we need to check the user-specified factory class.

Throws:

SAXException

handleEvent

public void handleEvent(ValidationEvent event,
                        boolean canRecover)
                 throws SAXException

Reports an error to the user, and asks if s/he wants to recover. If the canRecover flag is false, regardless of the client instruction, an exception will be thrown. Only if the flag is true and the user wants to recover from an error, the method returns normally. The thrown exception will be catched by the unmarshaller.

Throws:

SAXException

handleEvent

public boolean handleEvent(ValidationEvent event)

Description copied from interface: ValidationEventHandler

Receive notification of a validation warning or error. The ValidationEvent will have a ValidationEventLocator embedded in it that indicates where the error or warning occurred.

If an unchecked runtime exception is thrown from this method, the JAXB provider will treat it as if the method returned false and interrupt the current unmarshal, validate, or marshal operation.

Specified by:

handleEvent in interface ValidationEventHandler

Parameters:

event - the encapsulated validation event information. It is a provider error if this parameter is null.

Returns:

true if the JAXB Provider should attempt to continue the current unmarshal, validate, or marshal operation after handling this warning/error, false if the provider should terminate the current operation with the appropriate UnmarshalException, ValidationException, or MarshalException.

handleError

public void handleError(Exception e)
                 throws SAXException

Reports an exception found during the unmarshalling to the user. This method is a convenience method that calls into handleEvent(ValidationEvent, boolean)

Throws:

SAXException

handleError

public void handleError(Exception e,
                        boolean canRecover)
                 throws SAXException

Throws:

SAXException

handleError

public void handleError(String msg)

getLocation

protected ValidationEventLocator getLocation()

Description copied from class: Coordinator

Gets the current location. Used for reporting the error source location.

Specified by:

getLocation in class Coordinator

getLocator

public LocatorEx getLocator()

Gets the current source location information in SAX Locator.

Sometimes the unmarshaller works against a different kind of XML source, making this information meaningless.

errorUnresolvedIDREF

public void errorUnresolvedIDREF(Object bean,
                                 String idref,
                                 LocatorEx loc)
                          throws SAXException

Called when there's no corresponding ID value.

Throws:

SAXException

addPatcher

public void addPatcher(Patcher job)

Adds a job that will be executed at the last of the unmarshalling. This method is used to support ID/IDREF feature, but it can be used for other purposes as well.

Parameters:

job - The run method of this object is called.

addToIdTable

public String addToIdTable(String id)
                    throws SAXException

Adds the object which is currently being unmarshalled to the ID table.

Returns:

Returns the value passed as the parameter. This is a hack, but this makes it easier for ID transducer to do its job.

Throws:

SAXException

getObjectFromId

public Callable getObjectFromId(String id,
                                Class targetType)
                         throws SAXException

Looks up the ID table and gets associated object.

The exception thrown from Callable.call() means the unmarshaller should abort right away.

Throws:

SAXException

See Also:

IDResolver.resolve(String, Class)

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)

Description copied from interface: XmlVisitor

Called before XmlVisitor.startElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify a new namespace binding.

Specified by:

startPrefixMapping in interface XmlVisitor

endPrefixMapping

public void endPrefixMapping(String prefix)

Description copied from interface: XmlVisitor

Called after XmlVisitor.endElement(com.sun.xml.bind.v2.runtime.unmarshaller.TagName) event to notify the end of a binding.

Specified by:

endPrefixMapping in interface XmlVisitor

getNewlyDeclaredPrefixes

public String[] getNewlyDeclaredPrefixes()

Returns a list of prefixes newly declared on the current element.

Returns:

A possible zero-length array of prefixes. The default prefix is represented by the empty string.

getAllDeclaredPrefixes

public String[] getAllDeclaredPrefixes()

Returns a list of all in-scope prefixes.

Returns:

A possible zero-length array of prefixes. The default prefix is represented by the empty string.

getPrefixes

public Iterator<String> getPrefixes(String uri)

Specified by:

getPrefixes in interface NamespaceContext

getPrefix

public String getPrefix(String uri)

Specified by:

getPrefix in interface NamespaceContext

getNamespaceURI

public String getNamespaceURI(String prefix)

Specified by:

getNamespaceURI in interface NamespaceContext

startScope

public void startScope(int frameSize)

Starts a new packing scope.

This method allocates a specified number of fresh Scope objects. They can be accessed by the getScope(int) method until the corresponding endScope(int) method is invoked.

A new scope will mask the currently active scope. Only one frame of Scopes can be accessed at any given time.

Parameters:

frameSize - The # of slots to be allocated.

endScope

public void endScope(int frameSize)
              throws SAXException

Ends the current packing scope.

If any packing in progress will be finalized by this method.

Parameters:

frameSize - The same size that gets passed to the startScope(int) method.

Throws:

SAXException

getScope

public Scope getScope(int offset)

Gets the currently active Scope.

Parameters:

offset - a number between [0,frameSize)

Returns:

always a valid Scope object.

recordInnerPeer

public void recordInnerPeer(Object innerPeer)

Notifies the context about the inner peer of the current element.

If the unmarshalling is building the association, the context will use this information. Otherwise it will be just ignored.

getInnerPeer

public Object getInnerPeer()

Gets the inner peer JAXB object associated with the current element.

Returns:

null if the current element doesn't have an inner peer, or if we are not doing the in-place unmarshalling.

recordOuterPeer

public void recordOuterPeer(Object outerPeer)

Notifies the context about the outer peer of the current element.

If the unmarshalling is building the association, the context will use this information. Otherwise it will be just ignored.

getOuterPeer

public Object getOuterPeer()

Gets the outer peer JAXB object associated with the current element.

Returns:

null if the current element doesn't have an inner peer, or if we are not doing the in-place unmarshalling.

getXMIMEContentType

public String getXMIMEContentType()

Gets the xmime:contentType value for the current object.

See Also:

JAXBContextImpl.getXMIMEContentType(Object)

getInstance

public static UnmarshallingContext getInstance()

When called from within the realm of the unmarshaller, this method returns the current UnmarshallingContext in charge.

getCurrentExpectedElements

public Collection<QName> getCurrentExpectedElements()

Allows to access elements which are expected in current state. Useful for getting elements for current parent.

Returns:

getCurrentExpectedAttributes

public Collection<QName> getCurrentExpectedAttributes()

Allows to access attributes which are expected in current state. Useful for getting attributes for current parent.

Returns:

getStructureLoader

public StructureLoader getStructureLoader()

Gets StructureLoader if used as loader. Useful when determining if element is mixed or not.

shouldErrorBeReported

public boolean shouldErrorBeReported()
                              throws SAXException

Based on current Logger Level and errorCounter value determines if error should be reported. If the method called and return true it is expected that error will be reported. And that's why errorCounter is automatically decremented during the check. NOT THREAD SAFE!!! In case of heave concurrency access several additional errors could be reported. It's not expected to be the problem. Otherwise add synchronization here.

Returns:

true in case if Level.FINEST is set OR we haven't exceed errors reporting limit.

Throws:

SAXException