1 /* 2 * Copyright (c) 1999, 2013, 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 javax.naming; 27 28 import java.util.Hashtable; 29 30 /** 31 * This abstract class is used to represent a referral exception, 32 * which is generated in response to a <em>referral</em> 33 * such as that returned by LDAP v3 servers. 34 * <p> 35 * A service provider provides 36 * a subclass of {@code ReferralException} by providing implementations 37 * for {@code getReferralInfo()} and {@code getReferralContext()} (and appropriate 38 * constructors and/or corresponding "set" methods). 39 * <p> 40 * The following code sample shows how {@code ReferralException} can be used. 41 * <blockquote><pre>{@code 42 * while (true) { 43 * try { 44 * bindings = ctx.listBindings(name); 45 * while (bindings.hasMore()) { 46 * b = bindings.next(); 47 * ... 48 * } 49 * break; 50 * } catch (ReferralException e) { 51 * ctx = e.getReferralContext(); 52 * } 53 * } 54 * }</pre></blockquote> 55 *<p> 56 * {@code ReferralException} is an abstract class. Concrete implementations 57 * determine its synchronization and serialization properties. 58 *<p> 59 * An environment parameter passed to the {@code getReferralContext()} 60 * method is owned by the caller. 61 * The service provider will not modify the object or keep a reference to it, 62 * but may keep a reference to a clone of it. 63 * 64 * @author Rosanna Lee 65 * @author Scott Seligman 66 * 67 * @since 1.3 68 * 69 */ 70 71 public abstract class ReferralException extends NamingException { 72 /** 73 * Constructs a new instance of ReferralException using the 74 * explanation supplied. All other fields are set to null. 75 * 76 * @param explanation Additional detail about this exception. Can be null. 77 * @see java.lang.Throwable#getMessage 78 */ ReferralException(String explanation)79 protected ReferralException(String explanation) { 80 super(explanation); 81 } 82 83 /** 84 * Constructs a new instance of ReferralException. 85 * All fields are set to null. 86 */ ReferralException()87 protected ReferralException() { 88 super(); 89 } 90 91 /** 92 * Retrieves information (such as URLs) related to this referral. 93 * The program may examine or display this information 94 * to the user to determine whether to continue with the referral, 95 * or to determine additional information needs to be supplied in order 96 * to continue with the referral. 97 * 98 * @return Non-null referral information related to this referral. 99 */ getReferralInfo()100 public abstract Object getReferralInfo(); 101 102 /** 103 * Retrieves the context at which to continue the method. 104 * Regardless of whether a referral is encountered directly during a 105 * context operation, or indirectly, for example, during a search 106 * enumeration, the referral exception should provide a context 107 * at which to continue the operation. The referral context is 108 * created using the environment properties of the context 109 * that threw the ReferralException. 110 * 111 *<p> 112 * To continue the operation, the client program should re-invoke 113 * the method using the same arguments as the original invocation. 114 * 115 * @return The non-null context at which to continue the method. 116 * @exception NamingException If a naming exception was encountered. 117 * Call either {@code retryReferral()} or {@code skipReferral()} 118 * to continue processing referrals. 119 */ getReferralContext()120 public abstract Context getReferralContext() throws NamingException; 121 122 /** 123 * Retrieves the context at which to continue the method using 124 * environment properties. 125 * Regardless of whether a referral is encountered directly during a 126 * context operation, or indirectly, for example, during a search 127 * enumeration, the referral exception should provide a context 128 * at which to continue the operation. 129 *<p> 130 * The referral context is created using {@code env} as its environment 131 * properties. 132 * This method should be used instead of the no-arg overloaded form 133 * when the caller needs to use different environment properties for 134 * the referral context. It might need to do this, for example, when 135 * it needs to supply different authentication information to the referred 136 * server in order to create the referral context. 137 *<p> 138 * To continue the operation, the client program should re-invoke 139 * the method using the same arguments as the original invocation. 140 * 141 * @param env The possibly null environment to use when retrieving the 142 * referral context. If null, no environment properties will be used. 143 * 144 * @return The non-null context at which to continue the method. 145 * @exception NamingException If a naming exception was encountered. 146 * Call either {@code retryReferral()} or {@code skipReferral()} 147 * to continue processing referrals. 148 */ 149 public abstract Context getReferralContext(Hashtable<?,?> env)150 getReferralContext(Hashtable<?,?> env) 151 throws NamingException; 152 153 /** 154 * Discards the referral about to be processed. 155 * A call to this method should be followed by a call to 156 * {@code getReferralContext} to allow the processing of 157 * other referrals to continue. 158 * The following code fragment shows a typical usage pattern. 159 * <blockquote><pre> 160 * } catch (ReferralException e) { 161 * if (!shallIFollow(e.getReferralInfo())) { 162 * if (!e.skipReferral()) { 163 * return; 164 * } 165 * } 166 * ctx = e.getReferralContext(); 167 * } 168 * </pre></blockquote> 169 * 170 * @return true If more referral processing is pending; false otherwise. 171 */ skipReferral()172 public abstract boolean skipReferral(); 173 174 /** 175 * Retries the referral currently being processed. 176 * A call to this method should be followed by a call to 177 * {@code getReferralContext} to allow the current 178 * referral to be retried. 179 * The following code fragment shows a typical usage pattern. 180 * <blockquote><pre> 181 * } catch (ReferralException e) { 182 * while (true) { 183 * try { 184 * ctx = e.getReferralContext(env); 185 * break; 186 * } catch (NamingException ne) { 187 * if (! shallIRetry()) { 188 * return; 189 * } 190 * // modify environment properties (env), if necessary 191 * e.retryReferral(); 192 * } 193 * } 194 * } 195 * </pre></blockquote> 196 * 197 */ retryReferral()198 public abstract void retryReferral(); 199 200 /** 201 * Use serialVersionUID from JNDI 1.1.1 for interoperability 202 */ 203 private static final long serialVersionUID = -2881363844695698876L; 204 } 205