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 org.apache.harmony.jndi.internal.nls.Messages;
021:
022: /**
023: * A <code>NamingException</code> is the basic exception thrown by the naming
024: * classes. There are numerous subclasses of it which are used to further
025: * describe the type of error encountered.
026: * <p>
027: * A <code>NamingException</code> can hold information relating to an error
028: * encountered when trying to resolve a <code>Name</code>. It holds the two
029: * parts of the original name, firstly the part of the name which was
030: * successfully resolved, secondly the part of the name which could not be
031: * resolved.
032: * </p>
033: * <p>
034: * For example:<br />
035: * ------------<br />
036: * The resolved name could be something like http://www.apache.org where jndi
037: * has successfully resolved the DNS name. The part of the name which could not
038: * be resolved could be something like java/classes.index.html where jndi could
039: * not resolve the file name.
040: * </p>
041: * <p>
042: * It can also refer to the object that is associated with the resolved name.
043: * </p>
044: * <p>
045: * Additionally it can refer to another exception, which may be the root cause
046: * of this exception.
047: * </p>
048: * <p>
049: * Multithreaded access to a <code>NamingException</code> instance is only
050: * safe when client code locks the object first.
051: * </p>
052: */
053: public class NamingException extends Exception {
054:
055: /*
056: * This constant is used during deserialization to check the version which
057: * created the serialized object.
058: */
059: private static final long serialVersionUID = -1299181962103167177L;
060:
061: /**
062: * The resolved name. This may be null.
063: */
064: protected Name resolvedName = null;
065:
066: /**
067: * The remaining name. This may be null.
068: */
069: protected Name remainingName = null;
070:
071: /**
072: * The resolved object. This may be null.
073: */
074: protected Object resolvedObj = null;
075:
076: /**
077: * The exception that caused this NamingException to be raised. This may be
078: * null.
079: */
080: protected Throwable rootException = null;
081:
082: /**
083: * Constructs a <code>NamingException</code> instance with all data
084: * initialized to null.
085: */
086: public NamingException() {
087: super ();
088: }
089:
090: /**
091: * Constructs a <code>NamingException</code> instance with the specified
092: * message. All other fields are initialized to null.
093: *
094: * @param s
095: * The detail message for the exception. It may be null.
096: */
097: public NamingException(String s) {
098: super (s);
099: }
100:
101: /**
102: * Returns the message passed in as a param to the constructor. This may be
103: * null.
104: *
105: * @return the message passed in as a param to the constructor.
106: */
107: public String getExplanation() {
108: return super .getMessage();
109: }
110:
111: /**
112: * Appends the supplied string to the <code>Name</code> held as the
113: * remaining name. The string may be null.
114: *
115: * @param s
116: * the string to append to the remaining Name.
117: * @throws IllegalArgumentException
118: * if appending the supplied String s causes the name to become
119: * invalid.
120: */
121: public void appendRemainingComponent(String s) {
122: if (null != s) {
123: try {
124: if (null == remainingName) {
125: remainingName = new CompositeName(""); //$NON-NLS-1$
126: }
127: remainingName = remainingName.add(s);
128: } catch (InvalidNameException e) {
129: // jndi.10=Found invalid name, reason: {0}
130: throw new IllegalArgumentException(Messages.getString(
131: "jndi.10", e)); //$NON-NLS-1$
132: }
133: }
134: }
135:
136: /**
137: * Returns the remaining name. This may be null.
138: *
139: * @return the remaining name. This may be null.
140: */
141: public Name getRemainingName() {
142: return remainingName;
143: }
144:
145: /**
146: * Returns the resolved name. This may be null.
147: *
148: * @return the resolved name. This may be null.
149: */
150: public Name getResolvedName() {
151: return resolvedName;
152: }
153:
154: /**
155: * Returns the resolved object. This may be null.
156: *
157: * @return the resolved object. This may be null.
158: */
159: public Object getResolvedObj() {
160: return resolvedObj;
161: }
162:
163: /**
164: * Sets the resolved name to the specified name. This may be null. The
165: * resolved name details must not change even if the original
166: * <code>Name</code> itself changes.
167: *
168: * @param name
169: * the resolved name to set.
170: */
171: public void setResolvedName(Name name) {
172: resolvedName = null == name ? null : (Name) name.clone();
173: }
174:
175: /**
176: * Sets the remaining name to the specified n. This may be null. The
177: * remaining name details must not change even if the original
178: * <code>Name</code> itself changes.
179: *
180: * @param name
181: * the remaining name to set.
182: */
183: public void setRemainingName(Name name) {
184: remainingName = null == name ? null : (Name) name.clone();
185: }
186:
187: /**
188: * Sets the resolved object to the specified o. This may be null.
189: *
190: * @param o
191: * the resolved object to set.
192: */
193: public void setResolvedObj(Object o) {
194: resolvedObj = o;
195: }
196:
197: /**
198: * Appends the elements of the supplied <code>Name</code> n to the
199: * <code>Name</code> held as the remaining name. The <code>Name</code> n
200: * may be null or may be empty.
201: *
202: * @param n
203: * the name to append to the remaining name.
204: * @throws IllegalArgumentException
205: * if appending the supplied <code>Name</code> n causes the
206: * name to become invalid.
207: */
208: public void appendRemainingName(Name n) {
209: if (null != n) {
210: try {
211: if (null == remainingName) {
212: remainingName = new CompositeName(""); //$NON-NLS-1$
213: }
214: remainingName = remainingName.addAll(n);
215: } catch (InvalidNameException e) {
216: // jndi.10=Found invalid name, reason: {0}
217: throw new IllegalArgumentException(Messages.getString(
218: "jndi.10", e)); //$NON-NLS-1$
219: }
220: }
221: }
222:
223: /**
224: * Returns the exception which caused this <code>NamingException</code>
225: * which may be null.
226: *
227: * @return the exception which caused this <code>NamingException</code>
228: * which may be null.
229: */
230: public Throwable getRootCause() {
231: return rootException;
232: }
233:
234: /**
235: * Sets the exception that caused this <code>NamingException</code>. It
236: * may be null. Ignore the supplied parameter if it is actually this
237: * exception.
238: *
239: * @param t
240: * the exception that caused this <code>NamingException</code>.
241: */
242: public void setRootCause(Throwable t) {
243: if (t != this ) {
244: rootException = t;
245: }
246: }
247:
248: /**
249: * Returns the same details as the <code>toString()</code> method except
250: * that, if the <code>flag</code> is set to true, then details of the
251: * resolved object are also appended to the string. The actual format can be
252: * decided by the implementor.
253: *
254: * @param flag
255: * Indicates if the resolved object need to be returned.
256: *
257: * @return the string representation of this <code>NamingException</code>.
258: */
259: public String toString(boolean flag) {
260: return toStringImpl(flag);
261: }
262:
263: /*
264: * (non-Javadoc)
265: *
266: * @see java.lang.Throwable#getCause()
267: */
268: @Override
269: public Throwable getCause() {
270: return getRootCause();
271: }
272:
273: /*
274: * (non-Javadoc)
275: *
276: * @see java.lang.Throwable#initCause(Throwable)
277: */
278: @Override
279: public Throwable initCause(Throwable cause) {
280: super .initCause(cause);
281: rootException = cause;
282: return this ;
283: }
284:
285: /**
286: * Returns the string representation of this <code>NamingException</code>.
287: * The string contains the string representation of this exception together
288: * with details of the exception which caused this and any remaining portion
289: * of the <code>Name</code>.
290: * <p>
291: * The actual format can be decided by the implementor.
292: * </p>
293: *
294: * @return the string
295: */
296: @Override
297: public String toString() {
298: return this .toStringImpl(false);
299: }
300:
301: @SuppressWarnings("nls")
302: private String toStringImpl(boolean flag) {
303: StringBuffer sb = new StringBuffer();
304: sb.append(super .toString());
305: if (null != rootException) {
306: sb.append(" [Root exception is ").append(
307: rootException.toString()).append("]");
308: }
309: if (null != remainingName) {
310: sb.append("; Remaining name: '").append(
311: remainingName.toString()).append("'");
312: }
313: if (flag && null != resolvedObj) {
314: sb.append("; Resolved object: '").append(
315: resolvedObj.toString()).append("'");
316: }
317: return sb.toString();
318: }
319:
320: }
|