View Javadoc
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;
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 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</code>.  It is a composite name.
97       * If null, then no name is specified.
98       * See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>
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</code> is specified.  If null, then the default initial
116      * context is implied.
117      * See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>
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()</code>.
193      *<p>
194      * <tt>newName</tt> 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</code> is made and stored.
201      * Subsequent changes to <code>name</code> 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</code> field of this exception.
218      * This is the name of the resolved object, relative to the context
219      * <code>altNameCtx</code>. It will be used during a subsequent call to the
220      * <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.
221      *
222      * @return The name of the resolved object, relative to
223      *          <code>altNameCtx</code>.
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</code> field of this exception.
236      *
237      * @param altName   The name of the resolved object, relative to
238      *                  <code>altNameCtx</code>.
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</code> field of this exception.
251      * This is the context relative to which <code>altName</code> is named.
252      * It will be used during a subsequent call to the
253      * <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.
254      *
255      * @return  The context relative to which <code>altName</code> 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</code> field of this exception.
268      *
269      * @param altNameCtx
270      *                  The context relative to which <code>altName</code>
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 }