001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.xml.internal.bind;
027:
028: import java.util.concurrent.Future;
029: import java.util.concurrent.Callable;
030: import java.util.concurrent.Executors;
031:
032: import javax.xml.bind.annotation.XmlIDREF;
033: import javax.xml.bind.Unmarshaller;
034: import javax.xml.bind.ValidationEventHandler;
035:
036: import org.xml.sax.SAXException;
037:
038: /**
039: * Pluggable ID/IDREF handling layer.
040: *
041: * <p>
042: * <b>THIS INTERFACE IS SUBJECT TO CHANGE WITHOUT NOTICE.</b>
043: *
044: * <p>
045: * This 'interface' can be implemented by applications and specified to
046: * {@link Unmarshaller#setProperty(String, Object)} to ovierride the ID/IDREF
047: * processing of the JAXB RI like this:
048: *
049: * <pre>
050: * unmarshaller.setProperty(IDResolver.class.getName(),new MyIDResolverImpl());
051: * </pre>
052: *
053: * <h2>Error Handling</h2>
054: * <p>
055: * This component runs inside the JAXB RI unmarshaller. Therefore, it needs
056: * to coordinate with the JAXB RI unmarshaller when it comes to reporting
057: * errors. This makes sure that applications see consistent error handling behaviors.
058: *
059: * <p>
060: * When the {@link #startDocument(ValidationEventHandler)} method is invoked,
061: * the unmarshaller passes in a {@link ValidationEventHandler} that can be used
062: * by this component to report any errors encountered during the ID/IDREF processing.
063: *
064: * <p>
065: * When an error is detected, the error should be first reported to this
066: * {@link ValidationEventHandler}. If the error is fatal or the event handler
067: * decided to abort, the implementation should throw a {@link SAXException}.
068: * This signals the unmarshaller to abort the processing.
069: *
070: * @author Kohsuke Kawaguchi
071: * @since JAXB 2.0 beta
072: */
073: public abstract class IDResolver {
074:
075: /**
076: * Called when the unmarshalling starts.
077: *
078: * <p>
079: * Since one {@link Unmarshaller} may be used multiple times
080: * to unmarshal documents, one {@link IDResolver} may be used multiple times, too.
081: *
082: * @param eventHandler
083: * Any errors found during the unmarshalling should be reported to this object.
084: */
085: public void startDocument(ValidationEventHandler eventHandler)
086: throws SAXException {
087:
088: }
089:
090: /**
091: * Called after the unmarshalling completes.
092: *
093: * <p>
094: * This is a good opporunity to reset any internal state of this object,
095: * so that it doesn't keep references to other objects unnecessarily.
096: */
097: public void endDocument() throws SAXException {
098:
099: }
100:
101: /**
102: * Binds the given object to the specified ID.
103: *
104: * <p>
105: * While a document is being unmarshalled, every time
106: * an ID value is found, this method is invoked to
107: * remember the association between ID and objects.
108: * This association is supposed to be used later to resolve
109: * IDREFs.
110: *
111: * <p>
112: * This method is invoked right away as soon as a new ID value is found.
113: *
114: * @param id
115: * The ID value found in the document being unmarshalled.
116: * Always non-null.
117: * @param obj
118: * The object being unmarshalled which is going to own the ID.
119: * Always non-null.
120: */
121: public abstract void bind(String id, Object obj)
122: throws SAXException;
123:
124: /**
125: * Obtains the object to be pointed by the IDREF value.
126: *
127: * <p>
128: * While a document is being unmarshalled, every time
129: * an IDREF value is found, this method is invoked immediately to
130: * obtain the object that the IDREF is pointing to.
131: *
132: * <p>
133: * This method returns a {@link Callable} to support forward-references.
134: * When this method returns with a non-null return value,
135: * the JAXB RI unmarshaller invokes the {@link Callable#call()} method immediately.
136: * If the implementation can find the target object (in which case
137: * it was a backward reference), then a non-null object shall be returned,
138: * and it is used as the target object.
139: *
140: * <p>
141: * When a forward-reference happens, the <tt>call</tt> method
142: * should return null. In this case the JAXB RI unmarshaller invokes
143: * the <tt>call</tt> method again after all the documents are fully unmarshalled.
144: * If the <tt>call</tt> method still returns null, then the JAXB RI unmarshaller
145: * treats it as an error.
146: *
147: * <p>
148: * A {@link Callable} object returned from this method may not throw
149: * any exception other than a {@link SAXException} (which means a fatal error.)
150: *
151: * @param id
152: * The IDREF value found in the document being unmarshalled.
153: * Always non-null.
154: * @param targetType
155: * The expected type to which ID resolves to. JAXB infers this
156: * information from the signature of the fields that has {@link XmlIDREF}.
157: * When a property is a collection, this parameter will be the type
158: * of the individual item in the collection.
159: * @return
160: * null if the implementation is sure that the parameter combination
161: * will never yield a valid object. Otherwise non-null.
162: */
163: public abstract Callable<?> resolve(String id, Class targetType)
164: throws SAXException;
165: }
|