1 /*
2 * Copyright (c) 1997, 2012, 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 */
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 */
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 */
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 {@code call} method
138 * should return null. In this case the JAXB RI unmarshaller invokes
139 * the {@code call} method again after all the documents are fully unmarshalled.
140 * If the {@code call} 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 */
159 public abstract Callable<?> resolve( String id, Class targetType ) throws SAXException;
160 }