001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming;
019:
020: import java.util.Hashtable;
021:
022: /**
023: * Naming operations throw a <code>CannotProceedException</code> when the
024: * service provider context implementation is resolving a name but reaches a
025: * name component that does not belong to the namespace of the current context.
026: * <p>
027: * The service provider is able to create a <code>CannotProceedException</code>
028: * object and use methods on that object (including baseclass methods) to
029: * provide full details of how far name resolution had progressed.
030: * </p>
031: * <p>
032: * Typically, the methods used might include:
033: * <ul>
034: * <li><code>setEnvironment</code> to record the environment from the current
035: * context</li>
036: * <li> <code>setAltNameCtx</code> to record the current context</li>
037: * <li> <code>setResolvedObj</code> to record the resolved object for the next
038: * naming system</li>
039: * <li> <code>setAltName</code> to record the name of the resolved object</li>
040: * <li> <code>setRemainingName</code> to record the remaining unresolved name</li>
041: * </ul>
042: * </p>
043: * <p>
044: * If the incomplete naming operation is <code>rename</code>, the service
045: * provider should also use the <code>setRemainingNewName</code> method to
046: * record the unresolved part of the new name.
047: * </p>
048: * <p>
049: * The service provider can pass the <code>CannotProceedException</code> as a
050: * parameter to <code>NamingManager</code> methods such as
051: * <code>getContinuationContext</code> to attempt to locate another service
052: * provider for the next naming system. If successful, that service provider can
053: * return a new <code>Context</code> object on which the naming operation can
054: * proceed further. If unsuccessful, the <code>CannotProceedException</code>
055: * can be thrown by the service provider so that the JNDI application can handle
056: * it and take appropriate action.
057: * </p>
058: * <p>
059: * Multithreaded access to a single <code>CannotProceedException</code>
060: * instance is only safe when client code uses appropriate synchronization and
061: * locking.
062: * </p>
063: *
064: */
065: public class CannotProceedException extends NamingException {
066:
067: /*
068: * This constant is used during deserialization to check the version which
069: * created the serialized object.
070: */
071: private final static long serialVersionUID = 1219724816191576813L;
072:
073: /**
074: * Contains a composite name that is the name of the resolved object which
075: * is relative to the context in <code>altNameCtx</code>. This field may
076: * be null and is initially null. This field should be accessed and modified
077: * using only <code>getAltName</code> and <code>setAltName</code>.
078: */
079: protected Name altName = null;
080:
081: /**
082: * Contains the context to which the <code>altName</code> field is
083: * relative. This field may be null and is initially null. A null value
084: * implies the default initial context. This field should be accessed and
085: * modified using only <code>getAltNameCtx</code> and
086: * <code>setAltNameCtx</code>.
087: */
088: protected Context altNameCtx = null;
089:
090: /**
091: * Contains the environment of the context in which name resolution for the
092: * naming operation could not proceed further. Initially null. Should only
093: * be manipulated using <code>getEnvironment</code> and
094: * <code>setEnvironment methods</code>.
095: */
096: protected Hashtable<?, ?> environment = null;
097:
098: /**
099: * Contains a composite name that is the unresolved part of the new name
100: * that was specified in a <code>Context.rename</code> operation and may
101: * be used to continue the <code>rename</code> operation. This field may
102: * be null and is initially null. This field should be accessed and modified
103: * using only <code>getRemainingNewName</code> and
104: * <code>setRemainingNewName</code>.
105: */
106: protected Name remainingNewName = null;
107:
108: /**
109: * Constructs a <code>CannotProceedException</code> object. All
110: * unspecified fields are initialized to null.
111: */
112: public CannotProceedException() {
113: super ();
114: }
115:
116: /**
117: * Constructs a <code>CannotProceedException</code> object with an
118: * optionally specified <code>String</code> parameter containing a
119: * detailed explanation message. The <code>String</code> parameter may be
120: * null. All unspecified fields are initialized to null.
121: *
122: * @param s
123: * The detailed explanation message for the exception. It may be
124: * null.
125: */
126: public CannotProceedException(String s) {
127: super (s);
128: }
129:
130: /**
131: * Retrieves the value of the <code>altName</code> field.
132: *
133: * @return the value of the <code>altName</code> field.
134: * @see javax.naming.spi.ObjectFactory#getObjectInstance(Object, Name,
135: * Context, Hashtable)
136: */
137: public Name getAltName() {
138: return altName;
139: }
140:
141: /**
142: * Retrieves the value of the <code>altNameCtx</code> field.
143: *
144: * @return the value of the <code>altNameCtx</code> field.
145: * @see javax.naming.spi.ObjectFactory#getObjectInstance(Object, Name,
146: * Context, Hashtable)
147: */
148: public Context getAltNameCtx() {
149: return altNameCtx;
150: }
151:
152: /**
153: * Retrieves the value of the protected field <code>environment</code>
154: * which may be null.
155: *
156: * @return the value of the protected field <code>environment</code> which
157: * may be null.
158: */
159: public Hashtable<?, ?> getEnvironment() {
160: return environment;
161: }
162:
163: /**
164: * Retrieves the value of the <code>remainingNewName</code> field.
165: *
166: * @return the value of the <code>remainingNewName</code> field.
167: */
168: public Name getRemainingNewName() {
169: return remainingNewName;
170: }
171:
172: /**
173: * Modifies the value of the <code>altName</code> field to the specified
174: * <code>Name</code> parameter which is a composite name and may be null.
175: *
176: * @param name
177: * the name to set.
178: */
179: public void setAltName(Name name) {
180: altName = name;
181: }
182:
183: /**
184: * Modifies the value of the <code>altNameCtx</code> field to the
185: * specified <code>Context</code> parameter which may be null.
186: *
187: * @param context
188: * the new context to set.
189: */
190: public void setAltNameCtx(Context context) {
191: altNameCtx = context;
192: }
193:
194: /**
195: * Sets the value of the protected field <code>environment</code> from the
196: * <code>environment</code> parameter which may be null.
197: *
198: * @param hashtable
199: * the new environment to set.
200: */
201: public void setEnvironment(Hashtable<?, ?> hashtable) {
202: environment = hashtable;
203: }
204:
205: /**
206: * Modifies the value of the <code>remainingNewName</code> field to the
207: * specified parameter which may be null. But otherwise is a composite name.
208: * When needing to specify other names, first convert them into a composite
209: * name with a single component, and then specify that composite name when
210: * invoking this method.
211: * <p>
212: * When a non-null name is specified, a clone of the composite name is
213: * stored in the <code>remainingNewName</code> field that becomes
214: * independent of the specified name.
215: * </p>
216: *
217: * @param name
218: * the new name to set.
219: */
220: public void setRemainingNewName(Name name) {
221: remainingNewName = (null == name) ? null : (Name) name.clone();
222: }
223:
224: }
|