JAXB OSGI 4.0.9 · org.glassfish.jaxb.runtime.IDResolver

Pluggable ID/IDREF handling layer.

THIS INTERFACE IS SUBJECT TO CHANGE WITHOUT NOTICE.

This 'interface' can be implemented by applications and specified to Unmarshaller#setProperty(String, Object) to ovierride the ID/IDREF processing of the JAXB RI like this:

unmarshaller.setProperty(IDResolver.class.getName(),new MyIDResolverImpl());

Error Handling

This component runs inside the JAXB RI unmarshaller. Therefore, it needs to coordinate with the JAXB RI unmarshaller when it comes to reporting errors. This makes sure that applications see consistent error handling behaviors.

When the startDocument(ValidationEventHandler) method is invoked, the unmarshaller passes in a ValidationEventHandler that can be used by this component to report any errors encountered during the ID/IDREF processing.

When an error is detected, the error should be first reported to this ValidationEventHandler. If the error is fatal or the event handler decided to abort, the implementation should throw a SAXException. This signals the unmarshaller to abort the processing.

Access	Constructor and Description
protected	IDResolver() Default constructor.

Method Summary

Modifier and Type	Method and Description
public abstract void	bind(String The ID value found in the document being unmarshalled. Always non-null. id, Object The object being unmarshalled which is going to own the ID. Always non-null. obj) Binds the given object to the specified ID. While a document is being unmarshalled, every time an ID value is found, this method is invoked to remember the association between ID and objects.
public void	endDocument() Called after the unmarshalling completes.
public abstract Callable<?>	Returns: null if the implementation is sure that the parameter combination will never yield a valid object. Otherwise non-null. resolve(String The IDREF value found in the document being unmarshalled. Always non-null. id, Class<T> The expected type to which ID resolves to. JAXB infers this information from the signature of the fields that has `XmlIDREF`. When a property is a collection, this parameter will be the type of the individual item in the collection. targetType) Obtains the object to be pointed by the IDREF value.
public void	startDocument(ValidationEventHandler Any errors found during the unmarshalling should be reported to this object. eventHandler) Called when the unmarshalling starts.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

IDResolver	back to summary
protected IDResolver() Default constructor.

Method Detail

bind	back to summary
public abstract void bind(String id, Object obj) throws SAXException Binds the given object to the specified ID. While a document is being unmarshalled, every time an ID value is found, this method is invoked to remember the association between ID and objects. This association is supposed to be used later to resolve IDREFs. This method is invoked right away as soon as a new ID value is found. Parameters id:String The ID value found in the document being unmarshalled. Always non-null. obj:Object The object being unmarshalled which is going to own the ID. Always non-null.

bind

back to summary

public abstract void bind(String id, Object obj) throws SAXException

Binds the given object to the specified ID.

While a document is being unmarshalled, every time an ID value is found, this method is invoked to remember the association between ID and objects. This association is supposed to be used later to resolve IDREFs.

This method is invoked right away as soon as a new ID value is found.

Parameters

id:String: The ID value found in the document being unmarshalled. Always non-null.
obj:Object: The object being unmarshalled which is going to own the ID. Always non-null.

endDocument	back to summary
public void endDocument() throws SAXException Called after the unmarshalling completes. This is a good opporunity to reset any internal state of this object, so that it doesn't keep references to other objects unnecessarily.

endDocument

back to summary

public void endDocument() throws SAXException

Called after the unmarshalling completes.

This is a good opporunity to reset any internal state of this object, so that it doesn't keep references to other objects unnecessarily.

resolve back to summary

resolve	back to summary
public abstract Callable<?> resolve(String id, Class<T> targetType) throws SAXException Obtains the object to be pointed by the IDREF value. While a document is being unmarshalled, every time an IDREF value is found, this method is invoked immediately to obtain the object that the IDREF is pointing to. This method returns a `Callable` to support forward-references. When this method returns with a non-null return value, the JAXB RI unmarshaller invokes the `Callable#call()` method immediately. If the implementation can find the target object (in which case it was a backward reference), then a non-null object shall be returned, and it is used as the target object. When a forward-reference happens, the `call` method should return null. In this case the JAXB RI unmarshaller invokes the `call` method again after all the documents are fully unmarshalled. If the `call` method still returns null, then the JAXB RI unmarshaller treats it as an error. A `Callable` object returned from this method may not throw any exception other than a `SAXException` (which means a fatal error.) Parameters id:String The IDREF value found in the document being unmarshalled. Always non-null. targetType:Class<T> The expected type to which ID resolves to. JAXB infers this information from the signature of the fields that has `XmlIDREF`. When a property is a collection, this parameter will be the type of the individual item in the collection. Returns:Callable<?> null if the implementation is sure that the parameter combination will never yield a valid object. Otherwise non-null.

public abstract Callable<?> resolve(String id, Class<T> targetType) throws SAXException

Obtains the object to be pointed by the IDREF value.

While a document is being unmarshalled, every time an IDREF value is found, this method is invoked immediately to obtain the object that the IDREF is pointing to.

This method returns a Callable to support forward-references. When this method returns with a non-null return value, the JAXB RI unmarshaller invokes the Callable#call() method immediately. If the implementation can find the target object (in which case it was a backward reference), then a non-null object shall be returned, and it is used as the target object.

When a forward-reference happens, the call method should return null. In this case the JAXB RI unmarshaller invokes the call method again after all the documents are fully unmarshalled. If the call method still returns null, then the JAXB RI unmarshaller treats it as an error.

A Callable object returned from this method may not throw any exception other than a SAXException (which means a fatal error.)

Parameters

id:String: The IDREF value found in the document being unmarshalled. Always non-null.
targetType:Class<T>: The expected type to which ID resolves to. JAXB infers this information from the signature of the fields that has XmlIDREF. When a property is a collection, this parameter will be the type of the individual item in the collection.

Returns:Callable<?>

null if the implementation is sure that the parameter combination will never yield a valid object. Otherwise non-null.

startDocument back to summary

startDocument	back to summary
public void startDocument(ValidationEventHandler eventHandler) throws SAXException Called when the unmarshalling starts. Since one `Unmarshaller` may be used multiple times to unmarshal documents, one may be used multiple times, too. Parameters eventHandler:ValidationEventHandler Any errors found during the unmarshalling should be reported to this object.

public void startDocument(ValidationEventHandler eventHandler) throws SAXException

Called when the unmarshalling starts.

Since one Unmarshaller may be used multiple times to unmarshal documents, one may be used multiple times, too.

Parameters

eventHandler:ValidationEventHandler: Any errors found during the unmarshalling should be reported to this object.

public abstract Class IDResolver

Error Handling

Constructor Summary

Method Summary

Constructor Detail

Method Detail