1 /* 2 * Copyright (c) 1999, 2004, 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.ldap; 27 28 import javax.naming.ReferralException; 29 import javax.naming.Context; 30 import javax.naming.NamingException; 31 import java.util.Hashtable; 32 33 /** 34 * This abstract class is used to represent an LDAP referral exception. 35 * It extends the base <tt>ReferralException</tt> by providing a 36 * <tt>getReferralContext()</tt> method that accepts request controls. 37 * LdapReferralException is an abstract class. Concrete implementations of it 38 * determine its synchronization and serialization properties. 39 *<p> 40 * A <tt>Control[]</tt> array passed as a parameter to 41 * the <tt>getReferralContext()</tt> method is owned by the caller. 42 * The service provider will not modify the array or keep a reference to it, 43 * although it may keep references to the individual <tt>Control</tt> objects 44 * in the array. 45 * 46 * @author Rosanna Lee 47 * @author Scott Seligman 48 * @author Vincent Ryan 49 * @since 1.3 50 */ 51 52 public abstract class LdapReferralException extends ReferralException { 53 /** 54 * Constructs a new instance of LdapReferralException using the 55 * explanation supplied. All other fields are set to null. 56 * 57 * @param explanation Additional detail about this exception. Can be null. 58 * @see java.lang.Throwable#getMessage 59 */ 60 protected LdapReferralException(String explanation) { 61 super(explanation); 62 } 63 64 /** 65 * Constructs a new instance of LdapReferralException. 66 * All fields are set to null. 67 */ 68 protected LdapReferralException() { 69 super(); 70 } 71 72 /** 73 * Retrieves the context at which to continue the method using the 74 * context's environment and no controls. 75 * The referral context is created using the environment properties of 76 * the context that threw the <tt>ReferralException</tt> and no controls. 77 *<p> 78 * This method is equivalent to 79 *<blockquote><pre> 80 * getReferralContext(ctx.getEnvironment(), null); 81 *</pre></blockquote> 82 * where <tt>ctx</tt> is the context that threw the <tt>ReferralException.</tt> 83 *<p> 84 * It is overridden in this class for documentation purposes only. 85 * See <tt>ReferralException</tt> for how to use this method. 86 * 87 * @return The non-null context at which to continue the method. 88 * @exception NamingException If a naming exception was encountered. 89 * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt> 90 * to continue processing referrals. 91 */ 92 public abstract Context getReferralContext() throws NamingException; 93 94 /** 95 * Retrieves the context at which to continue the method using 96 * environment properties and no controls. 97 * The referral context is created using <tt>env</tt> as its environment 98 * properties and no controls. 99 *<p> 100 * This method is equivalent to 101 *<blockquote><pre> 102 * getReferralContext(env, null); 103 *</pre></blockquote> 104 *<p> 105 * It is overridden in this class for documentation purposes only. 106 * See <tt>ReferralException</tt> for how to use this method. 107 * 108 * @param env The possibly null environment to use when retrieving the 109 * referral context. If null, no environment properties will be used. 110 * 111 * @return The non-null context at which to continue the method. 112 * @exception NamingException If a naming exception was encountered. 113 * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt> 114 * to continue processing referrals. 115 */ 116 public abstract Context 117 getReferralContext(Hashtable<?,?> env) 118 throws NamingException; 119 120 /** 121 * Retrieves the context at which to continue the method using 122 * request controls and environment properties. 123 * Regardless of whether a referral is encountered directly during a 124 * context operation, or indirectly, for example, during a search 125 * enumeration, the referral exception should provide a context 126 * at which to continue the operation. 127 * To continue the operation, the client program should re-invoke 128 * the method using the same arguments as the original invocation. 129 *<p> 130 * <tt>reqCtls</tt> is used when creating the connection to the referred 131 * server. These controls will be used as the connection request controls for 132 * the context and context instances 133 * derived from the context. 134 * <tt>reqCtls</tt> will also be the context's request controls for 135 * subsequent context operations. See the <tt>LdapContext</tt> class 136 * description for details. 137 *<p> 138 * This method should be used instead of the other two overloaded forms 139 * when the caller needs to supply request controls for creating 140 * the referral context. It might need to do this, for example, when 141 * it needs to supply special controls relating to authentication. 142 *<p> 143 * Service provider implementors should read the "Service Provider" section 144 * in the <tt>LdapContext</tt> class description for implementation details. 145 * 146 * @param reqCtls The possibly null request controls to use for the new context. 147 * If null or the empty array means use no request controls. 148 * @param env The possibly null environment properties to use when 149 * for the new context. If null, the context is initialized with no environment 150 * properties. 151 * @return The non-null context at which to continue the method. 152 * @exception NamingException If a naming exception was encountered. 153 * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt> 154 * to continue processing referrals. 155 */ 156 public abstract Context 157 getReferralContext(Hashtable<?,?> env, 158 Control[] reqCtls) 159 throws NamingException; 160 161 private static final long serialVersionUID = -1668992791764950804L; 162 }