CannotProceedException.java revision 12515:4543b422c7d3 
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
26package javax.naming;
27
28import 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
63public 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    protected Context altNameCtx = null;
131
132    /**
133     * Constructs a new instance of CannotProceedException using an
134     * explanation. All unspecified fields default to null.
135     *
136     * @param   explanation     A possibly null string containing additional
137     *                          detail about this exception.
138     *   If null, this exception has no detail message.
139     * @see java.lang.Throwable#getMessage
140     */
141    public CannotProceedException(String explanation) {
142        super(explanation);
143    }
144
145    /**
146      * Constructs a new instance of CannotProceedException.
147      * All fields default to null.
148      */
149    public CannotProceedException() {
150        super();
151    }
152
153    /**
154     * Retrieves the environment that was in effect when this exception
155     * was created.
156     * @return Possibly null environment property set.
157     *          null means no environment was recorded for this exception.
158     * @see #setEnvironment
159     */
160    public Hashtable<?,?> getEnvironment() {
161        return environment;
162    }
163
164    /**
165     * Sets the environment that will be returned when getEnvironment()
166     * is called.
167     * @param environment A possibly null environment property set.
168     *          null means no environment is being recorded for
169     *          this exception.
170     * @see #getEnvironment
171     */
172    public void setEnvironment(Hashtable<?,?> environment) {
173        this.environment = environment; // %%% clone it??
174    }
175
176    /**
177     * Retrieves the "remaining new name" field of this exception, which is
178     * used when this exception is thrown during a rename() operation.
179     *
180     * @return The possibly null part of the new name that has not been resolved.
181     *          It is a composite name. It can be null, which means
182     *          the remaining new name field has not been set.
183     *
184     * @see #setRemainingNewName
185     */
186    public Name getRemainingNewName() {
187        return remainingNewName;
188    }
189
190    /**
191     * Sets the "remaining new name" field of this exception.
192     * This is the value returned by {@code getRemainingNewName()}.
193     *<p>
194     * {@code newName} is a composite name. If the intent is to set
195     * this field using a compound name or string, you must
196     * "stringify" the compound name, and create a composite
197     * name with a single component using the string. You can then
198     * invoke this method using the resulting composite name.
199     *<p>
200     * A copy of {@code newName} is made and stored.
201     * Subsequent changes to {@code name} does not
202     * affect the copy in this NamingException and vice versa.
203     *
204     * @param newName The possibly null name to set the "remaining new name" to.
205     *          If null, it sets the remaining name field to null.
206     *
207     * @see #getRemainingNewName
208     */
209    public void setRemainingNewName(Name newName) {
210        if (newName != null)
211            this.remainingNewName = (Name)(newName.clone());
212        else
213            this.remainingNewName = null;
214    }
215
216    /**
217     * Retrieves the {@code altName} field of this exception.
218     * This is the name of the resolved object, relative to the context
219     * {@code altNameCtx}. It will be used during a subsequent call to the
220     * {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
221     *
222     * @return The name of the resolved object, relative to
223     *          {@code altNameCtx}.
224     *          It is a composite name.  If null, then no name is specified.
225     *
226     * @see #setAltName
227     * @see #getAltNameCtx
228     * @see javax.naming.spi.ObjectFactory#getObjectInstance
229     */
230    public Name getAltName() {
231        return altName;
232    }
233
234    /**
235     * Sets the {@code altName} field of this exception.
236     *
237     * @param altName   The name of the resolved object, relative to
238     *                  {@code altNameCtx}.
239     *                  It is a composite name.
240     *                  If null, then no name is specified.
241     *
242     * @see #getAltName
243     * @see #setAltNameCtx
244     */
245    public void setAltName(Name altName) {
246        this.altName = altName;
247    }
248
249    /**
250     * Retrieves the {@code altNameCtx} field of this exception.
251     * This is the context relative to which {@code altName} is named.
252     * It will be used during a subsequent call to the
253     * {@code javax.naming.spi.ObjectFactory.getObjectInstance} method.
254     *
255     * @return  The context relative to which {@code altName} is named.
256     *          If null, then the default initial context is implied.
257     *
258     * @see #setAltNameCtx
259     * @see #getAltName
260     * @see javax.naming.spi.ObjectFactory#getObjectInstance
261     */
262    public Context getAltNameCtx() {
263        return altNameCtx;
264    }
265
266    /**
267     * Sets the {@code altNameCtx} field of this exception.
268     *
269     * @param altNameCtx
270     *                  The context relative to which {@code altName}
271     *                  is named.  If null, then the default initial context
272     *                  is implied.
273     *
274     * @see #getAltNameCtx
275     * @see #setAltName
276     */
277    public void setAltNameCtx(Context altNameCtx) {
278        this.altNameCtx = altNameCtx;
279    }
280
281
282    /**
283     * Use serialVersionUID from JNDI 1.1.1 for interoperability
284     */
285    private static final long serialVersionUID = 1219724816191576813L;
286}
287