aoqi@0: * THIS INTERFACE IS SUBJECT TO CHANGE WITHOUT NOTICE. aoqi@0: * aoqi@0: *
aoqi@0: * This 'interface' can be implemented by applications and specified to aoqi@0: * {@link Unmarshaller#setProperty(String, Object)} to ovierride the ID/IDREF aoqi@0: * processing of the JAXB RI like this: aoqi@0: * aoqi@0: *
aoqi@0: * unmarshaller.setProperty(IDResolver.class.getName(),new MyIDResolverImpl()); aoqi@0: *aoqi@0: * aoqi@0: *
aoqi@0: * This component runs inside the JAXB RI unmarshaller. Therefore, it needs aoqi@0: * to coordinate with the JAXB RI unmarshaller when it comes to reporting aoqi@0: * errors. This makes sure that applications see consistent error handling behaviors. aoqi@0: * aoqi@0: *
aoqi@0: * When the {@link #startDocument(ValidationEventHandler)} method is invoked, aoqi@0: * the unmarshaller passes in a {@link ValidationEventHandler} that can be used aoqi@0: * by this component to report any errors encountered during the ID/IDREF processing. aoqi@0: * aoqi@0: *
aoqi@0: * When an error is detected, the error should be first reported to this aoqi@0: * {@link ValidationEventHandler}. If the error is fatal or the event handler aoqi@0: * decided to abort, the implementation should throw a {@link SAXException}. aoqi@0: * This signals the unmarshaller to abort the processing. aoqi@0: * aoqi@0: * @author Kohsuke Kawaguchi aoqi@0: * @since JAXB 2.0 beta aoqi@0: */ aoqi@0: public abstract class IDResolver { aoqi@0: aoqi@0: /** aoqi@0: * Called when the unmarshalling starts. aoqi@0: * aoqi@0: *
aoqi@0: * Since one {@link Unmarshaller} may be used multiple times aoqi@0: * to unmarshal documents, one {@link IDResolver} may be used multiple times, too. aoqi@0: * aoqi@0: * @param eventHandler aoqi@0: * Any errors found during the unmarshalling should be reported to this object. aoqi@0: */ aoqi@0: public void startDocument(ValidationEventHandler eventHandler) throws SAXException { aoqi@0: aoqi@0: } aoqi@0: aoqi@0: /** aoqi@0: * Called after the unmarshalling completes. aoqi@0: * aoqi@0: *
aoqi@0: * This is a good opporunity to reset any internal state of this object, aoqi@0: * so that it doesn't keep references to other objects unnecessarily. aoqi@0: */ aoqi@0: public void endDocument() throws SAXException { aoqi@0: aoqi@0: } aoqi@0: aoqi@0: /** aoqi@0: * Binds the given object to the specified ID. aoqi@0: * aoqi@0: *
aoqi@0: * While a document is being unmarshalled, every time aoqi@0: * an ID value is found, this method is invoked to aoqi@0: * remember the association between ID and objects. aoqi@0: * This association is supposed to be used later to resolve aoqi@0: * IDREFs. aoqi@0: * aoqi@0: *
aoqi@0: * This method is invoked right away as soon as a new ID value is found. aoqi@0: * aoqi@0: * @param id aoqi@0: * The ID value found in the document being unmarshalled. aoqi@0: * Always non-null. aoqi@0: * @param obj aoqi@0: * The object being unmarshalled which is going to own the ID. aoqi@0: * Always non-null. aoqi@0: */ aoqi@0: public abstract void bind( String id, Object obj ) throws SAXException; aoqi@0: aoqi@0: /** aoqi@0: * Obtains the object to be pointed by the IDREF value. aoqi@0: * aoqi@0: *
aoqi@0: * While a document is being unmarshalled, every time aoqi@0: * an IDREF value is found, this method is invoked immediately to aoqi@0: * obtain the object that the IDREF is pointing to. aoqi@0: * aoqi@0: *
aoqi@0: * This method returns a {@link Callable} to support forward-references. aoqi@0: * When this method returns with a non-null return value, aoqi@0: * the JAXB RI unmarshaller invokes the {@link Callable#call()} method immediately. aoqi@0: * If the implementation can find the target object (in which case aoqi@0: * it was a backward reference), then a non-null object shall be returned, aoqi@0: * and it is used as the target object. aoqi@0: * aoqi@0: *
aoqi@0: * When a forward-reference happens, the call method aoqi@0: * should return null. In this case the JAXB RI unmarshaller invokes aoqi@0: * the call method again after all the documents are fully unmarshalled. aoqi@0: * If the call method still returns null, then the JAXB RI unmarshaller aoqi@0: * treats it as an error. aoqi@0: * aoqi@0: *
aoqi@0: * A {@link Callable} object returned from this method may not throw aoqi@0: * any exception other than a {@link SAXException} (which means a fatal error.) aoqi@0: * aoqi@0: * @param id aoqi@0: * The IDREF value found in the document being unmarshalled. aoqi@0: * Always non-null. aoqi@0: * @param targetType aoqi@0: * The expected type to which ID resolves to. JAXB infers this aoqi@0: * information from the signature of the fields that has {@link XmlIDREF}. aoqi@0: * When a property is a collection, this parameter will be the type aoqi@0: * of the individual item in the collection. aoqi@0: * @return aoqi@0: * null if the implementation is sure that the parameter combination aoqi@0: * will never yield a valid object. Otherwise non-null. aoqi@0: */ aoqi@0: public abstract Callable resolve( String id, Class targetType ) throws SAXException; aoqi@0: }