https://openjdk.java.net/ 
/*
 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.bind;

import java.util.concurrent.Callable;

import javax.xml.bind.Unmarshaller;
import javax.xml.bind.ValidationEventHandler;
import javax.xml.bind.annotation.XmlIDREF;

import org.xml.sax.SAXException;


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. 
Author:Kohsuke Kawaguchi
Since:JAXB 2.0 beta
/**
 * Pluggable ID/IDREF handling layer.
 *
 * <p>
 * <b>THIS INTERFACE IS SUBJECT TO CHANGE WITHOUT NOTICE.</b>
 *
 * <p>
 * This 'interface' can be implemented by applications and specified to
 * {@link Unmarshaller#setProperty(String, Object)} to ovierride the ID/IDREF
 * processing of the JAXB RI like this:
 *
 * <pre>
 * unmarshaller.setProperty(IDResolver.class.getName(),new MyIDResolverImpl());
 * </pre>
 *
 * <h2>Error Handling</h2>
 * <p>
 * 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.
 *
 * <p>
 * When the {@link #startDocument(ValidationEventHandler)} method is invoked,
 * the unmarshaller passes in a {@link ValidationEventHandler} that can be used
 * by this component to report any errors encountered during the ID/IDREF processing.
 *
 * <p>
 * When an error is detected, the error should be first reported to this
 * {@link ValidationEventHandler}. If the error is fatal or the event handler
 * decided to abort, the implementation should throw a {@link SAXException}.
 * This signals the unmarshaller to abort the processing.
 *
 * @author Kohsuke Kawaguchi
 * @since JAXB 2.0 beta
 */
public abstract class IDResolver {

    
Called when the unmarshalling starts.

 Since one Unmarshaller may be used multiple times to unmarshal documents, one IDResolver may be used multiple times, too. 
Params:
  • eventHandler – 
     Any errors found during the unmarshalling should be reported to this object.
/**
     * Called when the unmarshalling starts.
     *
     * <p>
     * Since one {@link Unmarshaller} may be used multiple times
     * to unmarshal documents, one {@link IDResolver} may be used multiple times, too.
     *
     * @param eventHandler
     *      Any errors found during the unmarshalling should be reported to this object.
     */
    public void startDocument(ValidationEventHandler eventHandler) 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.

/**
     * Called after the unmarshalling completes.
     *
     * <p>
     * This is a good opporunity to reset any internal state of this object,
     * so that it doesn't keep references to other objects unnecessarily.
     */
    public void endDocument() 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.

Params:
  • id – 
     The ID value found in the document being unmarshalled.
     Always non-null.
  • obj – 
     The object being unmarshalled which is going to own the ID.
     Always non-null.
/**
     * Binds the given object to the specified ID.
     *
     * <p>
     * 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.
     *
     * <p>
     * This method is invoked right away as soon as a new ID value is found.
     *
     * @param id
     *      The ID value found in the document being unmarshalled.
     *      Always non-null.
     * @param obj
     *      The object being unmarshalled which is going to own the ID.
     *      Always non-null.
     */
    public abstract void bind( String id, Object obj ) 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.) 
Params:
  • id – 
     The IDREF value found in the document being unmarshalled.
     Always non-null.
  • targetType –  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:
     null if the implementation is sure that the parameter combination
     will never yield a valid object. Otherwise non-null.
/**
     * Obtains the object to be pointed by the IDREF value.
     *
     * <p>
     * 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.
     *
     * <p>
     * This method returns a {@link Callable} to support forward-references.
     * When this method returns with a non-null return value,
     * the JAXB RI unmarshaller invokes the {@link 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.
     *
     * <p>
     * When a forward-reference happens, the {@code call} method
     * should return null. In this case the JAXB RI unmarshaller invokes
     * the {@code call} method again after all the documents are fully unmarshalled.
     * If the {@code call} method still returns null, then the JAXB RI unmarshaller
     * treats it as an error.
     *
     * <p>
     * A {@link Callable} object returned from this method may not throw
     * any exception other than a {@link SAXException} (which means a fatal error.)
     *
     * @param id
     *      The IDREF value found in the document being unmarshalled.
     *      Always non-null.
     * @param targetType
     *      The expected type to which ID resolves to. JAXB infers this
     *      information from the signature of the fields that has {@link XmlIDREF}.
     *      When a property is a collection, this parameter will be the type
     *      of the individual item in the collection.
     * @return
     *      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 targetType ) throws SAXException;
}