--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.naming/share/classes/javax/naming/NamingException.java Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,435 @@
+/*
+ * 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> 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>
+ * <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> 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>
+ * <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> 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 <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;
+};