Back to index...

	/*
	* 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>
	* <tt>name</tt> 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</code> is made and stored.
	* Subsequent changes to <code>name</code> does 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>
	* <tt>name</tt> 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</code> is made and stored.
	* Subsequent changes to <code>name</code> does 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>
	* <tt>name</tt> 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</code> does 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 <tt>e</tt> is <tt>this</tt>, 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</code> if the cause is nonexistent or
	* unknown.
	*
	* @return the cause of this exception, or <code>null</code> 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 <tt>null</tt> value
	* indicates that the cause is nonexistent or unknown.
	* @return a reference to this <code>NamingException</code> instance.
	* @throws IllegalArgumentException if <code>cause</code> 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;
	};

Back to index...