1 /*
2 * Copyright (c) 1999, 2019, 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 exception is thrown to indicate that the operation reached
32 * a point in the name where the operation cannot proceed any further.
33 * When performing an operation on a composite name, a naming service
34 * provider may reach a part of the name that does not belong to its
35 * namespace. At that point, it can construct a
36 * CannotProceedException and then invoke methods provided by
37 * javax.naming.spi.NamingManager (such as getContinuationContext())
38 * to locate another provider to continue the operation. If this is
39 * not possible, this exception is raised to the caller of the
40 * context operation.
41 *<p>
42 * If the program wants to handle this exception in particular, it
43 * should catch CannotProceedException explicitly before attempting to
44 * catch NamingException.
45 *<p>
46 * A CannotProceedException instance is not synchronized against concurrent
47 * multithreaded access. Multiple threads trying to access and modify
48 * CannotProceedException should lock the object.
49 *
50 * @author Rosanna Lee
51 * @author Scott Seligman
52 * @since 1.3
53 */
54
55 /*
56 * The serialized form of a CannotProceedException object consists of
57 * the serialized fields of its NamingException superclass, the remaining new
58 * name (a Name object), the environment (a Hashtable), the altName field
59 * (a Name object), and the serialized form of the altNameCtx field.
60 */
61
62
63 public class CannotProceedException extends NamingException {
64 /**
65 * Contains the remaining unresolved part of the second
66 * "name" argument to Context.rename().
67 * This information is necessary for
68 * continuing the Context.rename() operation.
69 * <p>
70 * This field is initialized to null.
71 * It should not be manipulated directly: it should
72 * be accessed and updated using getRemainingName() and setRemainingName().
73 * @serial
74 *
75 * @see #getRemainingNewName
76 * @see #setRemainingNewName
77 */
78 protected Name remainingNewName = null;
79
80 /**
81 * Contains the environment
82 * relevant for the Context or DirContext method that cannot proceed.
83 * <p>
84 * This field is initialized to null.
85 * It should not be manipulated directly: it should be accessed
86 * and updated using getEnvironment() and setEnvironment().
87 * @serial
88 *
89 * @see #getEnvironment
90 * @see #setEnvironment
91 */
92 protected Hashtable<?,?> environment = null;
93
94 /**
95 * Contains the name of the resolved object, relative
96 * to the context {@code altNameCtx}. It is a composite name.
97 * If null, then no name is specified.
98 * See the {@code javax.naming.spi.ObjectFactory.getObjectInstance}
99 * method for details on how this is used.
100 * <p>
101 * This field is initialized to null.
102 * It should not be manipulated directly: it should
103 * be accessed and updated using getAltName() and setAltName().
104 * @serial
105 *
106 * @see #getAltName
107 * @see #setAltName
108 * @see #altNameCtx
109 * @see javax.naming.spi.ObjectFactory#getObjectInstance
110 */
111 protected Name altName = null;
112
113 /**
114 * Contains the context relative to which
115 * {@code altName} is specified. If null, then the default initial
116 * context is implied.
117 * See the {@code javax.naming.spi.ObjectFactory.getObjectInstance}
118 * method for details on how this is used.
119 * <p>
120 * This field is initialized to null.
121 * It should not be manipulated directly: it should
122 * be accessed and updated using getAltNameCtx() and setAltNameCtx().
123 * @serial
124 *
125 * @see #getAltNameCtx
126 * @see #setAltNameCtx
127 * @see #altName
128 * @see javax.naming.spi.ObjectFactory#getObjectInstance
129 */
130 @SuppressWarnings("serial") // Not statically typed as Serializable
131 protected Context altNameCtx = null;
132
133 /**
134 * Constructs a new instance of CannotProceedException using an
135 * explanation. All unspecified fields default to null.
136 *
137 * @param explanation A possibly null string containing additional
138 * detail about this exception.
139 * If null, this exception has no detail message.
140 * @see java.lang.Throwable#getMessage
141 */
142 public CannotProceedException(String explanation) {
143 super(explanation);
144 }
145
146 /**
147 * Constructs a new instance of CannotProceedException.
148 * All fields default to null.
149 */
150 public CannotProceedException() {
151 super();
152 }
153
154 /**
155 * Retrieves the environment that was in effect when this exception
156 * was created.
157 * @return Possibly null environment property set.
158 * null means no environment was recorded for this exception.
159 * @see #setEnvironment
160 */
161 public Hashtable<?,?> getEnvironment() {
162 return environment;
163 }
164
165 /**
166 * Sets the environment that will be returned when getEnvironment()
167 * is called.
168 * @param environment A possibly null environment property set.
169 * null means no environment is being recorded for
170 * this exception.
171 * @see #getEnvironment
172 */
173 public void setEnvironment(Hashtable<?,?> environment) {
174 this.environment = environment; // %%% clone it??
175 }
176
177 /**
178 * Retrieves the "remaining new name" field of this exception, which is
179 * used when this exception is thrown during a rename() operation.
180 *
181 * @return The possibly null part of the new name that has not been resolved.
182 * It is a composite name. It can be null, which means
183 * the remaining new name field has not been set.
184 *
185 * @see #setRemainingNewName
186 */
187 public Name getRemainingNewName() {
188 return remainingNewName;
189 }
190
191 /**
192 * Sets the "remaining new name" field of this exception.
193 * This is the value returned by {@code getRemainingNewName()}.
194 *<p>
195 * {@code newName} is a composite name. If the intent is to set
196 * this field using a compound name or string, you must
197 * "stringify" the compound name, and create a composite
198 * name with a single component using the string. You can then
199 * invoke this method using the resulting composite name.
200 *<p>
201 * A copy of {@code newName} is made and stored.
202 * Subsequent changes to {@code name} does not
203 * affect the copy in this NamingException and vice versa.
204 *
205 * @param newName The possibly null name to set the "remaining new name" to.
206 * If null, it sets the remaining name field to null.
207 *
208 * @see #getRemainingNewName
209 */
210 public void setRemainingNewName(Name newName) {
211 if (newName != null)
212 this.remainingNewName = (Name)(newName.clone());
213 else
214 this.remainingNewName = null;
215 }
216
217 /**
218 * Retrieves the {@code altName} field of this exception.
219 * This is the name of the resolved object, relative to the context
220 * {@code altNameCtx}. It will be used during a subsequent call to the
221 * {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
222 *
223 * @return The name of the resolved object, relative to
224 * {@code altNameCtx}.
225 * It is a composite name. If null, then no name is specified.
226 *
227 * @see #setAltName
228 * @see #getAltNameCtx
229 * @see javax.naming.spi.ObjectFactory#getObjectInstance
230 */
231 public Name getAltName() {
232 return altName;
233 }
234
235 /**
236 * Sets the {@code altName} field of this exception.
237 *
238 * @param altName The name of the resolved object, relative to
239 * {@code altNameCtx}.
240 * It is a composite name.
241 * If null, then no name is specified.
242 *
243 * @see #getAltName
244 * @see #setAltNameCtx
245 */
246 public void setAltName(Name altName) {
247 this.altName = altName;
248 }
249
250 /**
251 * Retrieves the {@code altNameCtx} field of this exception.
252 * This is the context relative to which {@code altName} is named.
253 * It will be used during a subsequent call to the
254 * {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
255 *
256 * @return The context relative to which {@code altName} is named.
257 * If null, then the default initial context is implied.
258 *
259 * @see #setAltNameCtx
260 * @see #getAltName
261 * @see javax.naming.spi.ObjectFactory#getObjectInstance
262 */
263 public Context getAltNameCtx() {
264 return altNameCtx;
265 }
266
267 /**
268 * Sets the {@code altNameCtx} field of this exception.
269 *
270 * @param altNameCtx
271 * The context relative to which {@code altName}
272 * is named. If null, then the default initial context
273 * is implied.
274 *
275 * @see #getAltNameCtx
276 * @see #setAltName
277 */
278 public void setAltNameCtx(Context altNameCtx) {
279 this.altNameCtx = altNameCtx;
280 }
281
282
283 /**
284 * Use serialVersionUID from JNDI 1.1.1 for interoperability
285 */
286 private static final long serialVersionUID = 1219724816191576813L;
287 }