CannotProceedException


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