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 {@code ReferralException} by providing a
36 * {@code getReferralContext()} 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 {@code Control[]} array passed as a parameter to
41 * the {@code getReferralContext()} 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 {@code Control} 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 {@code ReferralException} and no controls.
77 *<p>
78 * This method is equivalent to
79 *<blockquote><pre>
80 * getReferralContext(ctx.getEnvironment(), null);
81 *</pre></blockquote>
82 * where {@code ctx} is the context that threw the {@code ReferralException.}
83 *<p>
84 * It is overridden in this class for documentation purposes only.
85 * See {@code ReferralException} 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 {@code retryReferral()} or {@code skipReferral()}
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 {@code env} 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 {@code ReferralException} 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 {@code retryReferral()} or {@code skipReferral()}
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 * {@code reqCtls} 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 * {@code reqCtls} will also be the context's request controls for
135 * subsequent context operations. See the {@code LdapContext} 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 {@code LdapContext} 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 {@code retryReferral()} or {@code skipReferral()}
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 }