jdk/src/java.naming/share/classes/javax/naming/NamingException.java
author avstepan
Wed, 05 Aug 2015 13:40:18 +0300
changeset 32029 a5538163e144
parent 25859 3317bb8137f4
permissions -rw-r--r--
8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming Reviewed-by: lancea, dfuchs
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     2
 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package javax.naming;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
  * This is the superclass of all exceptions thrown by
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
  * operations in the Context and DirContext interfaces.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
  * The nature of the failure is described by the name of the subclass.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
  * This exception captures the information pinpointing where the operation
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
  * failed, such as where resolution last proceeded to.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
  * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
  * <li> Resolved Name. Portion of name that has been resolved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
  * <li> Resolved Object. Object to which resolution of name proceeded.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
  * <li> Remaining Name. Portion of name that has not been resolved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
  * <li> Explanation. Detail explaining why name resolution failed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
  * <li> Root Exception. The exception that caused this naming exception
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
  *                     to be thrown.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
  *</ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
  * null is an acceptable value for any of these fields. When null,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
  * it means that no such information has been recorded for that field.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
  *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
  * A NamingException instance is not synchronized against concurrent
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
  * multithreaded access. Multiple threads trying to access and modify
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
  * a single NamingException instance should lock the object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
  *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
  * This exception has been retrofitted to conform to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
  * the general purpose exception-chaining mechanism.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
  * <i>root exception</i> (or <i>root cause</i>) is the same object as the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
  * <i>cause</i> returned by the {@link Throwable#getCause()} method.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
  *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
  * @author Rosanna Lee
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
  * @author Scott Seligman
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
  * @since 1.3
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
  */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
public class NamingException extends Exception {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
     * Contains the part of the name that has been successfully resolved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
     * It is a composite name and can be null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
     * This field is initialized by the constructors.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
     * You should access and manipulate this field
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
     * through its get and set methods.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
     * @serial
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
     * @see #getResolvedName
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
     * @see #setResolvedName
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
    protected Name resolvedName;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
      * Contains the object to which resolution of the part of the name was
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
      * successful. Can be null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
      * This field is initialized by the constructors.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      * You should access and manipulate this field
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
      * through its get and set methods.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
      * @serial
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
      * @see #getResolvedObj
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
      * @see #setResolvedObj
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
    protected Object resolvedObj;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
     * Contains the remaining name that has not been resolved yet.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
     * It is a composite name and can be null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
     * This field is initialized by the constructors.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
     * You should access and manipulate this field
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
     * through its get, set, "append" methods.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
     * @serial
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
     * @see #getRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
     * @see #setRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
     * @see #appendRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
     * @see #appendRemainingComponent
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
    protected Name remainingName;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
     * Contains the original exception that caused this NamingException to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
     * be thrown. This field is set if there is additional
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
     * information that could be obtained from the original
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
     * exception, or if the original exception could not be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
     * mapped to a subclass of NamingException.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
     * Can be null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
     *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
     * This field predates the general-purpose exception chaining facility.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
     * The {@link #initCause(Throwable)} and {@link #getCause()} methods
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
     * are now the preferred means of accessing this information.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
     * @serial
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
     * @see #getRootCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
     * @see #setRootCause(Throwable)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
     * @see #initCause(Throwable)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
     * @see #getCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
    protected Throwable rootException = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
     * Constructs a new NamingException with an explanation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
     * All unspecified fields are set to null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
     * @param   explanation     A possibly null string containing
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
     *                          additional detail about this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     * @see java.lang.Throwable#getMessage
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
    public NamingException(String explanation) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
        super(explanation);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
        resolvedName = remainingName = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
        resolvedObj = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
      * Constructs a new NamingException.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
      * All fields are set to null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
    public NamingException() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
        super();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
        resolvedName = remainingName = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
        resolvedObj = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
     * Retrieves the leading portion of the name that was resolved
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
     * successfully.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
     * @return The part of the name that was resolved successfully.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
     *          It is a composite name. It can be null, which means
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
     *          the resolved name field has not been set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
     * @see #getResolvedObj
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
     * @see #setResolvedName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
    public Name getResolvedName() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
        return resolvedName;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
     * Retrieves the remaining unresolved portion of the name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
     * @return The part of the name that has not been resolved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
     *          It is a composite name. It can be null, which means
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
     *          the remaining name field has not been set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * @see #setRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     * @see #appendRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
     * @see #appendRemainingComponent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
    public Name getRemainingName() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
        return remainingName;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     * Retrieves the object to which resolution was successful.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     * This is the object to which the resolved name is bound.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     * @return The possibly null object that was resolved so far.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
     *  null means that the resolved object field has not been set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
     * @see #getResolvedName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
     * @see #setResolvedObj
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
    public Object getResolvedObj() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
        return resolvedObj;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
      * Retrieves the explanation associated with this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
      * @return The possibly null detail string explaining more
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
      *         about this exception. If null, it means there is no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
      *         detail message for this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
      * @see java.lang.Throwable#getMessage
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
    public String getExplanation() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
        return getMessage();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
     * Sets the resolved name field of this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
     *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   197
     * {@code name} is a composite name. If the intent is to set
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
     * this field using a compound name or string, you must
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
     * "stringify" the compound name, and create a composite
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
     * name with a single component using the string. You can then
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
     * invoke this method using the resulting composite name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
     *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   203
     * A copy of {@code name} is made and stored.
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   204
     * Subsequent changes to {@code name} do not
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
     * affect the copy in this NamingException and vice versa.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
     * @param name The possibly null name to set resolved name to.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
     *          If null, it sets the resolved name field to null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
     * @see #getResolvedName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
    public void setResolvedName(Name name) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
        if (name != null)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
            resolvedName = (Name)(name.clone());
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
        else
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
            resolvedName = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
     * Sets the remaining name field of this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
     *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   221
     * {@code name} is a composite name. If the intent is to set
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
     * this field using a compound name or string, you must
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
     * "stringify" the compound name, and create a composite
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
     * name with a single component using the string. You can then
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
     * invoke this method using the resulting composite name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
     *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   227
     * A copy of {@code name} is made and stored.
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   228
     * Subsequent changes to {@code name} do not
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
     * affect the copy in this NamingException and vice versa.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
     * @param name The possibly null name to set remaining name to.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
     *          If null, it sets the remaining name field to null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
     * @see #getRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
     * @see #appendRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
     * @see #appendRemainingComponent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
    public void setRemainingName(Name name) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
        if (name != null)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
            remainingName = (Name)(name.clone());
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
        else
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
            remainingName = null;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
     * Sets the resolved object field of this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
     * @param obj The possibly null object to set resolved object to.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
     *            If null, the resolved object field is set to null.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
     * @see #getResolvedObj
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
    public void setResolvedObj(Object obj) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
        resolvedObj = obj;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
      * Add name as the last component in remaining name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
      * @param name The component to add.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
      *         If name is null, this method does not do anything.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
      * @see #setRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
      * @see #getRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
      * @see #appendRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
    public void appendRemainingComponent(String name) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
        if (name != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
            try {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
                if (remainingName == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
                    remainingName = new CompositeName();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
                }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
                remainingName.add(name);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
            } catch (NamingException e) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
                throw new IllegalArgumentException(e.toString());
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
      * Add components from 'name' as the last components in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
      * remaining name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
      *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   278
      * {@code name} is a composite name. If the intent is to append
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
      * a compound name, you should "stringify" the compound name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
      * then invoke the overloaded form that accepts a String parameter.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
      *<p>
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   282
      * Subsequent changes to {@code name} do not
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
      * affect the remaining name field in this NamingException and vice versa.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
      * @param name The possibly null name containing ordered components to add.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
      *                 If name is null, this method does not do anything.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
      * @see #setRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
      * @see #getRemainingName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
      * @see #appendRemainingComponent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
    public void appendRemainingName(Name name) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
        if (name == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
            return;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
        if (remainingName != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
            try {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
                remainingName.addAll(name);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
            } catch (NamingException e) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
                throw new IllegalArgumentException(e.toString());
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
        } else {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
            remainingName = (Name)(name.clone());
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
      * Retrieves the root cause of this NamingException, if any.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
      * The root cause of a naming exception is used when the service provider
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
      * wants to indicate to the caller a non-naming related exception
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
      * but at the same time wants to use the NamingException structure
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
      * to indicate how far the naming operation proceeded.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
      *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
      * This method predates the general-purpose exception chaining facility.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
      * The {@link #getCause()} method is now the preferred means of obtaining
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
      * this information.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
      * @return The possibly null exception that caused this naming
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
      *    exception. If null, it means no root cause has been
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
      *    set for this naming exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   319
      * @see #setRootCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   320
      * @see #rootException
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
      * @see #getCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
    public Throwable getRootCause() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
        return rootException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   326
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
      * Records the root cause of this NamingException.
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   329
      * If {@code e} is {@code this}, this method does not do anything.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   330
      *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   331
      * This method predates the general-purpose exception chaining facility.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   332
      * The {@link #initCause(Throwable)} method is now the preferred means
90ce3da70b43 Initial load
duke
parents:
diff changeset
   333
      * of recording this information.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   334
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   335
      * @param e The possibly null exception that caused the naming
90ce3da70b43 Initial load
duke
parents:
diff changeset
   336
      *          operation to fail. If null, it means this naming
90ce3da70b43 Initial load
duke
parents:
diff changeset
   337
      *          exception has no root cause.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   338
      * @see #getRootCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   339
      * @see #rootException
90ce3da70b43 Initial load
duke
parents:
diff changeset
   340
      * @see #initCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   341
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   342
    public void setRootCause(Throwable e) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   343
        if (e != this) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   344
            rootException = e;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   345
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   346
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   347
90ce3da70b43 Initial load
duke
parents:
diff changeset
   348
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   349
      * Returns the cause of this exception.  The cause is the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   350
      * throwable that caused this naming exception to be thrown.
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   351
      * Returns {@code null} if the cause is nonexistent or
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   352
      * unknown.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   353
      *
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   354
      * @return  the cause of this exception, or {@code null} if the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   355
      *          cause is nonexistent or unknown.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   356
      * @see #initCause(Throwable)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   357
      * @since 1.4
90ce3da70b43 Initial load
duke
parents:
diff changeset
   358
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   359
    public Throwable getCause() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   360
        return getRootCause();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   361
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   362
90ce3da70b43 Initial load
duke
parents:
diff changeset
   363
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   364
      * Initializes the cause of this exception to the specified value.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   365
      * The cause is the throwable that caused this naming exception to be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   366
      * thrown.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   367
      *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   368
      * This method may be called at most once.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   369
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   370
      * @param  cause   the cause, which is saved for later retrieval by
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   371
      *         the {@link #getCause()} method.  A {@code null} value
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   372
      *         indicates that the cause is nonexistent or unknown.
32029
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   373
      * @return a reference to this {@code NamingException} instance.
a5538163e144 8132877: docs: replace <tt> tags (obsolete in html5) for javax.naming
avstepan
parents: 25859
diff changeset
   374
      * @throws IllegalArgumentException if {@code cause} is this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   375
      *         exception.  (A throwable cannot be its own cause.)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   376
      * @throws IllegalStateException if this method has already
90ce3da70b43 Initial load
duke
parents:
diff changeset
   377
      *         been called on this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   378
      * @see #getCause
90ce3da70b43 Initial load
duke
parents:
diff changeset
   379
      * @since 1.4
90ce3da70b43 Initial load
duke
parents:
diff changeset
   380
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   381
    public Throwable initCause(Throwable cause) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   382
        super.initCause(cause);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   383
        setRootCause(cause);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   384
        return this;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   385
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   386
90ce3da70b43 Initial load
duke
parents:
diff changeset
   387
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   388
     * Generates the string representation of this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   389
     * The string representation consists of this exception's class name,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   390
     * its detailed message, and if it has a root cause, the string
90ce3da70b43 Initial load
duke
parents:
diff changeset
   391
     * representation of the root cause exception, followed by
90ce3da70b43 Initial load
duke
parents:
diff changeset
   392
     * the remaining name (if it is not null).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   393
     * This string is used for debugging and not meant to be interpreted
90ce3da70b43 Initial load
duke
parents:
diff changeset
   394
     * programmatically.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   395
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   396
     * @return The non-null string containing the string representation
90ce3da70b43 Initial load
duke
parents:
diff changeset
   397
     * of this exception.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   398
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   399
    public String toString() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   400
        String answer = super.toString();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   401
90ce3da70b43 Initial load
duke
parents:
diff changeset
   402
        if (rootException != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   403
            answer += " [Root exception is " + rootException + "]";
90ce3da70b43 Initial load
duke
parents:
diff changeset
   404
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   405
        if (remainingName != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   406
            answer += "; remaining name '" + remainingName + "'";
90ce3da70b43 Initial load
duke
parents:
diff changeset
   407
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   408
        return answer;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   409
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   410
90ce3da70b43 Initial load
duke
parents:
diff changeset
   411
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   412
      * Generates the string representation in more detail.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   413
      * This string representation consists of the information returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   414
      * by the toString() that takes no parameters, plus the string
90ce3da70b43 Initial load
duke
parents:
diff changeset
   415
      * representation of the resolved object (if it is not null).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   416
      * This string is used for debugging and not meant to be interpreted
90ce3da70b43 Initial load
duke
parents:
diff changeset
   417
      * programmatically.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   418
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   419
      * @param detail If true, include details about the resolved object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   420
      *                 in addition to the other information.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   421
      * @return The non-null string containing the string representation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   422
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   423
    public String toString(boolean detail) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   424
        if (!detail || resolvedObj == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   425
            return toString();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   426
        } else {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   427
            return (toString() + "; resolved object " + resolvedObj);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   428
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   429
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   430
90ce3da70b43 Initial load
duke
parents:
diff changeset
   431
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   432
     * Use serialVersionUID from JNDI 1.1.1 for interoperability
90ce3da70b43 Initial load
duke
parents:
diff changeset
   433
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   434
    private static final long serialVersionUID = -1299181962103167177L;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   435
};