com.sun.xml.bind.IDResolver Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package com.sun.xml.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
* {@link 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 {@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.
*
*
* 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 {@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.
*/
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.
*
* @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 {@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.
*
*
* 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 {@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;
}