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 */
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 */
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 */
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 */
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
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>{@code
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 */
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>{@code
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 */
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 }