You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
436 lines
15 KiB
436 lines
15 KiB
/*
|
|
* Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
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;
|
|
};
|