Java tutorial
/* * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.naming; /** * This is the superclass of all exceptions thrown by * operations in the Context and DirContext interfaces. * The nature of the failure is described by the name of the subclass. * This exception captures the information pinpointing where the operation * failed, such as where resolution last proceeded to. * <ul> * <li> Resolved Name. Portion of name that has been resolved. * <li> Resolved Object. Object to which resolution of name proceeded. * <li> Remaining Name. Portion of name that has not been resolved. * <li> Explanation. Detail explaining why name resolution failed. * <li> Root Exception. The exception that caused this naming exception * to be thrown. *</ul> * null is an acceptable value for any of these fields. When null, * it means that no such information has been recorded for that field. *<p> * A NamingException instance is not synchronized against concurrent * multithreaded access. Multiple threads trying to access and modify * a single NamingException instance should lock the object. *<p> * This exception has been retrofitted to conform to * the general purpose exception-chaining mechanism. The * <i>root exception</i> (or <i>root cause</i>) is the same object as the * <i>cause</i> returned by the {@link Throwable#getCause()} method. * * @author Rosanna Lee * @author Scott Seligman * @since 1.3 */ public class NamingException extends Exception { /** * Contains the part of the name that has been successfully resolved. * It is a composite name and can be null. * This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getResolvedName * @see #setResolvedName */ protected Name resolvedName; /** * Contains the object to which resolution of the part of the name was * successful. Can be null. * This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getResolvedObj * @see #setResolvedObj */ protected Object resolvedObj; /** * Contains the remaining name that has not been resolved yet. * It is a composite name and can be null. * This field is initialized by the constructors. * You should access and manipulate this field * through its get, set, "append" methods. * @serial * @see #getRemainingName * @see #setRemainingName * @see #appendRemainingName * @see #appendRemainingComponent */ protected Name remainingName; /** * Contains the original exception that caused this NamingException to * be thrown. This field is set if there is additional * information that could be obtained from the original * exception, or if the original exception could not be * mapped to a subclass of NamingException. * Can be null. *<p> * This field predates the general-purpose exception chaining facility. * The {@link #initCause(Throwable)} and {@link #getCause()} methods * are now the preferred means of accessing this information. * * @serial * @see #getRootCause * @see #setRootCause(Throwable) * @see #initCause(Throwable) * @see #getCause */ protected Throwable rootException = null; /** * Constructs a new NamingException with an explanation. * All unspecified fields are set to null. * * @param explanation A possibly null string containing * additional detail about this exception. * @see java.lang.Throwable#getMessage */ public NamingException(String explanation) { super(explanation); resolvedName = remainingName = null; resolvedObj = null; } /** * Constructs a new NamingException. * All fields are set to null. */ public NamingException() { super(); resolvedName = remainingName = null; resolvedObj = null; } /** * Retrieves the leading portion of the name that was resolved * successfully. * * @return The part of the name that was resolved successfully. * It is a composite name. It can be null, which means * the resolved name field has not been set. * @see #getResolvedObj * @see #setResolvedName */ public Name getResolvedName() { return resolvedName; } /** * Retrieves the remaining unresolved portion of the name. * @return The part of the name that has not been resolved. * It is a composite name. It can be null, which means * the remaining name field has not been set. * @see #setRemainingName * @see #appendRemainingName * @see #appendRemainingComponent */ public Name getRemainingName() { return remainingName; } /** * Retrieves the object to which resolution was successful. * This is the object to which the resolved name is bound. * * @return The possibly null object that was resolved so far. * null means that the resolved object field has not been set. * @see #getResolvedName * @see #setResolvedObj */ public Object getResolvedObj() { return resolvedObj; } /** * Retrieves the explanation associated with this exception. * * @return The possibly null detail string explaining more * about this exception. If null, it means there is no * detail message for this exception. * * @see java.lang.Throwable#getMessage */ public String getExplanation() { return getMessage(); } /** * Sets the resolved name field of this exception. *<p> * {@code name} is a composite name. If the intent is to set * this field using a compound name or string, you must * "stringify" the compound name, and create a composite * name with a single component using the string. You can then * invoke this method using the resulting composite name. *<p> * A copy of {@code name} is made and stored. * Subsequent changes to {@code name} do not * affect the copy in this NamingException and vice versa. * * @param name The possibly null name to set resolved name to. * If null, it sets the resolved name field to null. * @see #getResolvedName */ public void setResolvedName(Name name) { if (name != null) resolvedName = (Name) (name.clone()); else resolvedName = null; } /** * Sets the remaining name field of this exception. *<p> * {@code name} is a composite name. If the intent is to set * this field using a compound name or string, you must * "stringify" the compound name, and create a composite * name with a single component using the string. You can then * invoke this method using the resulting composite name. *<p> * A copy of {@code name} is made and stored. * Subsequent changes to {@code name} do not * affect the copy in this NamingException and vice versa. * @param name The possibly null name to set remaining name to. * If null, it sets the remaining name field to null. * @see #getRemainingName * @see #appendRemainingName * @see #appendRemainingComponent */ public void setRemainingName(Name name) { if (name != null) remainingName = (Name) (name.clone()); else remainingName = null; } /** * Sets the resolved object field of this exception. * @param obj The possibly null object to set resolved object to. * If null, the resolved object field is set to null. * @see #getResolvedObj */ public void setResolvedObj(Object obj) { resolvedObj = obj; } /** * Add name as the last component in remaining name. * @param name The component to add. * If name is null, this method does not do anything. * @see #setRemainingName * @see #getRemainingName * @see #appendRemainingName */ public void appendRemainingComponent(String name) { if (name != null) { try { if (remainingName == null) { remainingName = new CompositeName(); } remainingName.add(name); } catch (NamingException e) { throw new IllegalArgumentException(e.toString()); } } } /** * Add components from 'name' as the last components in * remaining name. *<p> * {@code name} is a composite name. If the intent is to append * a compound name, you should "stringify" the compound name * then invoke the overloaded form that accepts a String parameter. *<p> * Subsequent changes to {@code name} do not * affect the remaining name field in this NamingException and vice versa. * @param name The possibly null name containing ordered components to add. * If name is null, this method does not do anything. * @see #setRemainingName * @see #getRemainingName * @see #appendRemainingComponent */ public void appendRemainingName(Name name) { if (name == null) { return; } if (remainingName != null) { try { remainingName.addAll(name); } catch (NamingException e) { throw new IllegalArgumentException(e.toString()); } } else { remainingName = (Name) (name.clone()); } } /** * Retrieves the root cause of this NamingException, if any. * The root cause of a naming exception is used when the service provider * wants to indicate to the caller a non-naming related exception * but at the same time wants to use the NamingException structure * to indicate how far the naming operation proceeded. *<p> * This method predates the general-purpose exception chaining facility. * The {@link #getCause()} method is now the preferred means of obtaining * this information. * * @return The possibly null exception that caused this naming * exception. If null, it means no root cause has been * set for this naming exception. * @see #setRootCause * @see #rootException * @see #getCause */ public Throwable getRootCause() { return rootException; } /** * Records the root cause of this NamingException. * If {@code e} is {@code this}, this method does not do anything. *<p> * This method predates the general-purpose exception chaining facility. * The {@link #initCause(Throwable)} method is now the preferred means * of recording this information. * * @param e The possibly null exception that caused the naming * operation to fail. If null, it means this naming * exception has no root cause. * @see #getRootCause * @see #rootException * @see #initCause */ public void setRootCause(Throwable e) { if (e != this) { rootException = e; } } /** * Returns the cause of this exception. The cause is the * throwable that caused this naming exception to be thrown. * Returns {@code null} if the cause is nonexistent or * unknown. * * @return the cause of this exception, or {@code null} if the * cause is nonexistent or unknown. * @see #initCause(Throwable) * @since 1.4 */ public Throwable getCause() { return getRootCause(); } /** * Initializes the cause of this exception to the specified value. * The cause is the throwable that caused this naming exception to be * thrown. *<p> * This method may be called at most once. * * @param cause the cause, which is saved for later retrieval by * the {@link #getCause()} method. A {@code null} value * indicates that the cause is nonexistent or unknown. * @return a reference to this {@code NamingException} instance. * @throws IllegalArgumentException if {@code cause} is this * exception. (A throwable cannot be its own cause.) * @throws IllegalStateException if this method has already * been called on this exception. * @see #getCause * @since 1.4 */ public Throwable initCause(Throwable cause) { super.initCause(cause); setRootCause(cause); return this; } /** * Generates the string representation of this exception. * The string representation consists of this exception's class name, * its detailed message, and if it has a root cause, the string * representation of the root cause exception, followed by * the remaining name (if it is not null). * This string is used for debugging and not meant to be interpreted * programmatically. * * @return The non-null string containing the string representation * of this exception. */ public String toString() { String answer = super.toString(); if (rootException != null) { answer += " [Root exception is " + rootException + "]"; } if (remainingName != null) { answer += "; remaining name '" + remainingName + "'"; } return answer; } /** * Generates the string representation in more detail. * This string representation consists of the information returned * by the toString() that takes no parameters, plus the string * representation of the resolved object (if it is not null). * This string is used for debugging and not meant to be interpreted * programmatically. * * @param detail If true, include details about the resolved object * in addition to the other information. * @return The non-null string containing the string representation. */ public String toString(boolean detail) { if (!detail || resolvedObj == null) { return toString(); } else { return (toString() + "; resolved object " + resolvedObj); } } /** * Use serialVersionUID from JNDI 1.1.1 for interoperability */ private static final long serialVersionUID = -1299181962103167177L; };