1 /*
2  * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package com.sun.xml.internal.bind;
27 
28 import java.util.concurrent.Callable;
29 
30 import javax.xml.bind.Unmarshaller;
31 import javax.xml.bind.ValidationEventHandler;
32 import javax.xml.bind.annotation.XmlIDREF;
33 
34 import org.xml.sax.SAXException;
35 
36 /**
37  * Pluggable ID/IDREF handling layer.
38  *
39  * <p>
40  * <b>THIS INTERFACE IS SUBJECT TO CHANGE WITHOUT NOTICE.</b>
41  *
42  * <p>
43  * This 'interface' can be implemented by applications and specified to
44  * {@link Unmarshaller#setProperty(String, Object)} to ovierride the ID/IDREF
45  * processing of the JAXB RI like this:
46  *
47  * <pre>
48  * unmarshaller.setProperty(IDResolver.class.getName(),new MyIDResolverImpl());
49  * </pre>
50  *
51  * <h2>Error Handling</h2>
52  * <p>
53  * This component runs inside the JAXB RI unmarshaller. Therefore, it needs
54  * to coordinate with the JAXB RI unmarshaller when it comes to reporting
55  * errors. This makes sure that applications see consistent error handling behaviors.
56  *
57  * <p>
58  * When the {@link #startDocument(ValidationEventHandler)} method is invoked,
59  * the unmarshaller passes in a {@link ValidationEventHandler} that can be used
60  * by this component to report any errors encountered during the ID/IDREF processing.
61  *
62  * <p>
63  * When an error is detected, the error should be first reported to this
64  * {@link ValidationEventHandler}. If the error is fatal or the event handler
65  * decided to abort, the implementation should throw a {@link SAXException}.
66  * This signals the unmarshaller to abort the processing.
67  *
68  * @author Kohsuke Kawaguchi
69  * @since JAXB 2.0 beta
70  */
71 public abstract class IDResolver {
72 
73     /**
74      * Called when the unmarshalling starts.
75      *
76      * <p>
77      * Since one {@link Unmarshaller} may be used multiple times
78      * to unmarshal documents, one {@link IDResolver} may be used multiple times, too.
79      *
80      * @param eventHandler
81      *      Any errors found during the unmarshalling should be reported to this object.
82      */
startDocument(ValidationEventHandler eventHandler)83     public void startDocument(ValidationEventHandler eventHandler) throws SAXException {
84 
85     }
86 
87     /**
88      * Called after the unmarshalling completes.
89      *
90      * <p>
91      * This is a good opporunity to reset any internal state of this object,
92      * so that it doesn't keep references to other objects unnecessarily.
93      */
endDocument()94     public void endDocument() throws SAXException {
95 
96     }
97 
98     /**
99      * Binds the given object to the specified ID.
100      *
101      * <p>
102      * While a document is being unmarshalled, every time
103      * an ID value is found, this method is invoked to
104      * remember the association between ID and objects.
105      * This association is supposed to be used later to resolve
106      * IDREFs.
107      *
108      * <p>
109      * This method is invoked right away as soon as a new ID value is found.
110      *
111      * @param id
112      *      The ID value found in the document being unmarshalled.
113      *      Always non-null.
114      * @param obj
115      *      The object being unmarshalled which is going to own the ID.
116      *      Always non-null.
117      */
bind( String id, Object obj )118     public abstract void bind( String id, Object obj ) throws SAXException;
119 
120     /**
121      * Obtains the object to be pointed by the IDREF value.
122      *
123      * <p>
124      * While a document is being unmarshalled, every time
125      * an IDREF value is found, this method is invoked immediately to
126      * obtain the object that the IDREF is pointing to.
127      *
128      * <p>
129      * This method returns a {@link Callable} to support forward-references.
130      * When this method returns with a non-null return value,
131      * the JAXB RI unmarshaller invokes the {@link Callable#call()} method immediately.
132      * If the implementation can find the target object (in which case
133      * it was a backward reference), then a non-null object shall be returned,
134      * and it is used as the target object.
135      *
136      * <p>
137      * When a forward-reference happens, the <tt>call</tt> method
138      * should return null. In this case the JAXB RI unmarshaller invokes
139      * the <tt>call</tt> method again after all the documents are fully unmarshalled.
140      * If the <tt>call</tt> method still returns null, then the JAXB RI unmarshaller
141      * treats it as an error.
142      *
143      * <p>
144      * A {@link Callable} object returned from this method may not throw
145      * any exception other than a {@link SAXException} (which means a fatal error.)
146      *
147      * @param id
148      *      The IDREF value found in the document being unmarshalled.
149      *      Always non-null.
150      * @param targetType
151      *      The expected type to which ID resolves to. JAXB infers this
152      *      information from the signature of the fields that has {@link XmlIDREF}.
153      *      When a property is a collection, this parameter will be the type
154      *      of the individual item in the collection.
155      * @return
156      *      null if the implementation is sure that the parameter combination
157      *      will never yield a valid object. Otherwise non-null.
158      */
resolve( String id, Class targetType )159     public abstract Callable<?> resolve( String id, Class targetType ) throws SAXException;
160 }
161