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 <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 */ 159 public abstract Callable<?> resolve( String id, Class targetType ) throws SAXException; 160 }