src/java.naming/share/classes/javax/naming/LinkException.java
changeset 47216 71c04702a3d5
parent 32029 a5538163e144
child 58531 9b40d05c9f66
equal deleted inserted replaced
47215:4ebc2e2fb97c 47216:71c04702a3d5
       
     1 /*
       
     2  * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
       
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       
     4  *
       
     5  * This code is free software; you can redistribute it and/or modify it
       
     6  * under the terms of the GNU General Public License version 2 only, as
       
     7  * published by the Free Software Foundation.  Oracle designates this
       
     8  * particular file as subject to the "Classpath" exception as provided
       
     9  * by Oracle in the LICENSE file that accompanied this code.
       
    10  *
       
    11  * This code is distributed in the hope that it will be useful, but WITHOUT
       
    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       
    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
       
    14  * version 2 for more details (a copy is included in the LICENSE file that
       
    15  * accompanied this code).
       
    16  *
       
    17  * You should have received a copy of the GNU General Public License version
       
    18  * 2 along with this work; if not, write to the Free Software Foundation,
       
    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
       
    20  *
       
    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
       
    22  * or visit www.oracle.com if you need additional information or have any
       
    23  * questions.
       
    24  */
       
    25 
       
    26 package javax.naming;
       
    27 
       
    28 /**
       
    29  * This exception is used to describe problems encountered while resolving links.
       
    30  * Additional information is added to the base NamingException for pinpointing
       
    31  * the problem with the link.
       
    32  *<p>
       
    33  * Analogously to how NamingException captures name resolution information,
       
    34  * LinkException captures "link"-name resolution information pinpointing
       
    35  * the problem encountered while resolving a link. All these fields may
       
    36  * be null.
       
    37  * <ul>
       
    38  * <li> Link Resolved Name. Portion of link name that has been resolved.
       
    39  * <li> Link Resolved Object. Object to which resolution of link name proceeded.
       
    40  * <li> Link Remaining Name. Portion of link name that has not been resolved.
       
    41  * <li> Link Explanation. Detail explaining why link resolution failed.
       
    42  *</ul>
       
    43  *
       
    44   *<p>
       
    45   * A LinkException instance is not synchronized against concurrent
       
    46   * multithreaded access. Multiple threads trying to access and modify
       
    47   * a single LinkException instance should lock the object.
       
    48   *
       
    49   * @author Rosanna Lee
       
    50   * @author Scott Seligman
       
    51   *
       
    52   * @see Context#lookupLink
       
    53   * @see LinkRef
       
    54   * @since 1.3
       
    55   */
       
    56 
       
    57 
       
    58   /*<p>
       
    59   * The serialized form of a LinkException object consists of the
       
    60   * serialized fields of its NamingException superclass, the link resolved
       
    61   * name (a Name object), the link resolved object, link remaining name
       
    62   * (a Name object), and the link explanation String.
       
    63 */
       
    64 
       
    65 
       
    66 public class LinkException extends NamingException {
       
    67     /**
       
    68      * Contains the part of the link that has been successfully resolved.
       
    69      * It is a composite name and can be null.
       
    70      * This field is initialized by the constructors.
       
    71      * You should access and manipulate this field
       
    72      * through its get and set methods.
       
    73      * @serial
       
    74      * @see #getLinkResolvedName
       
    75      * @see #setLinkResolvedName
       
    76      */
       
    77     protected Name linkResolvedName;
       
    78 
       
    79     /**
       
    80       * Contains the object to which resolution of the part of the link was successful.
       
    81       * Can be null. This field is initialized by the constructors.
       
    82       * You should access and manipulate this field
       
    83       * through its get and set methods.
       
    84       * @serial
       
    85       * @see #getLinkResolvedObj
       
    86       * @see #setLinkResolvedObj
       
    87       */
       
    88     protected Object linkResolvedObj;
       
    89 
       
    90     /**
       
    91      * Contains the remaining link name that has not been resolved yet.
       
    92      * It is a composite name and can be null.
       
    93      * This field is initialized by the constructors.
       
    94      * You should access and manipulate this field
       
    95      * through its get and set methods.
       
    96      * @serial
       
    97      * @see #getLinkRemainingName
       
    98      * @see #setLinkRemainingName
       
    99      */
       
   100     protected Name linkRemainingName;
       
   101 
       
   102     /**
       
   103      * Contains the exception of why resolution of the link failed.
       
   104      * Can be null. This field is initialized by the constructors.
       
   105      * You should access and manipulate this field
       
   106      * through its get and set methods.
       
   107      * @serial
       
   108      * @see #getLinkExplanation
       
   109      * @see #setLinkExplanation
       
   110      */
       
   111     protected String linkExplanation;
       
   112 
       
   113     /**
       
   114       * Constructs a new instance of LinkException with an explanation.
       
   115       * All the other fields are initialized to null.
       
   116       * @param  explanation     A possibly null string containing additional
       
   117       *                         detail about this exception.
       
   118       * @see java.lang.Throwable#getMessage
       
   119       */
       
   120     public LinkException(String explanation) {
       
   121         super(explanation);
       
   122         linkResolvedName = null;
       
   123         linkResolvedObj = null;
       
   124         linkRemainingName = null;
       
   125         linkExplanation = null;
       
   126     }
       
   127 
       
   128     /**
       
   129       * Constructs a new instance of LinkException.
       
   130       * All the non-link-related and link-related fields are initialized to null.
       
   131       */
       
   132     public LinkException() {
       
   133         super();
       
   134         linkResolvedName = null;
       
   135         linkResolvedObj = null;
       
   136         linkRemainingName = null;
       
   137         linkExplanation = null;
       
   138     }
       
   139 
       
   140     /**
       
   141      * Retrieves the leading portion of the link name that was resolved
       
   142      * successfully.
       
   143      *
       
   144      * @return The part of the link name that was resolved successfully.
       
   145      *          It is a composite name. It can be null, which means
       
   146      *          the link resolved name field has not been set.
       
   147      * @see #getLinkResolvedObj
       
   148      * @see #setLinkResolvedName
       
   149      */
       
   150     public Name getLinkResolvedName() {
       
   151         return this.linkResolvedName;
       
   152     }
       
   153 
       
   154     /**
       
   155      * Retrieves the remaining unresolved portion of the link name.
       
   156      * @return The part of the link name that has not been resolved.
       
   157      *          It is a composite name. It can be null, which means
       
   158      *          the link remaining name field has not been set.
       
   159      * @see #setLinkRemainingName
       
   160      */
       
   161     public Name getLinkRemainingName() {
       
   162         return this.linkRemainingName;
       
   163     }
       
   164 
       
   165     /**
       
   166      * Retrieves the object to which resolution was successful.
       
   167      * This is the object to which the resolved link name is bound.
       
   168      *
       
   169      * @return The possibly null object that was resolved so far.
       
   170      * If null, it means the link resolved object field has not been set.
       
   171      * @see #getLinkResolvedName
       
   172      * @see #setLinkResolvedObj
       
   173      */
       
   174     public Object getLinkResolvedObj() {
       
   175         return this.linkResolvedObj;
       
   176     }
       
   177 
       
   178     /**
       
   179       * Retrieves the explanation associated with the problem encountered
       
   180       * when resolving a link.
       
   181       *
       
   182       * @return The possibly null detail string explaining more about the problem
       
   183       * with resolving a link.
       
   184       *         If null, it means there is no
       
   185       *         link detail message for this exception.
       
   186       * @see #setLinkExplanation
       
   187       */
       
   188     public String getLinkExplanation() {
       
   189         return this.linkExplanation;
       
   190     }
       
   191 
       
   192     /**
       
   193       * Sets the explanation associated with the problem encountered
       
   194       * when resolving a link.
       
   195       *
       
   196       * @param msg The possibly null detail string explaining more about the problem
       
   197       * with resolving a link. If null, it means no detail will be recorded.
       
   198       * @see #getLinkExplanation
       
   199       */
       
   200     public void setLinkExplanation(String msg) {
       
   201         this.linkExplanation = msg;
       
   202     }
       
   203 
       
   204     /**
       
   205      * Sets the resolved link name field of this exception.
       
   206      *<p>
       
   207      * {@code name} is a composite name. If the intent is to set
       
   208      * this field using a compound name or string, you must
       
   209      * "stringify" the compound name, and create a composite
       
   210      * name with a single component using the string. You can then
       
   211      * invoke this method using the resulting composite name.
       
   212      *<p>
       
   213      * A copy of <code>name</code> is made and stored.
       
   214      * Subsequent changes to <code>name</code> do not
       
   215      * affect the copy in this NamingException and vice versa.
       
   216      *
       
   217      *
       
   218      * @param name The name to set resolved link name to. This can be null.
       
   219      *          If null, it sets the link resolved name field to null.
       
   220      * @see #getLinkResolvedName
       
   221      */
       
   222     public void setLinkResolvedName(Name name) {
       
   223         if (name != null) {
       
   224             this.linkResolvedName = (Name)(name.clone());
       
   225         } else {
       
   226             this.linkResolvedName = null;
       
   227         }
       
   228     }
       
   229 
       
   230     /**
       
   231      * Sets the remaining link name field of this exception.
       
   232      *<p>
       
   233      * {@code name} is a composite name. If the intent is to set
       
   234      * this field using a compound name or string, you must
       
   235      * "stringify" the compound name, and create a composite
       
   236      * name with a single component using the string. You can then
       
   237      * invoke this method using the resulting composite name.
       
   238      *<p>
       
   239      * A copy of <code>name</code> is made and stored.
       
   240      * Subsequent changes to <code>name</code> do not
       
   241      * affect the copy in this NamingException and vice versa.
       
   242      *
       
   243      * @param name The name to set remaining link name to. This can be null.
       
   244      *  If null, it sets the remaining name field to null.
       
   245      * @see #getLinkRemainingName
       
   246      */
       
   247     public void setLinkRemainingName(Name name) {
       
   248         if (name != null)
       
   249             this.linkRemainingName = (Name)(name.clone());
       
   250         else
       
   251             this.linkRemainingName = null;
       
   252     }
       
   253 
       
   254     /**
       
   255      * Sets the link resolved object field of this exception.
       
   256      * This indicates the last successfully resolved object of link name.
       
   257      * @param obj The object to set link resolved object to. This can be null.
       
   258      *            If null, the link resolved object field is set to null.
       
   259      * @see #getLinkResolvedObj
       
   260      */
       
   261     public void setLinkResolvedObj(Object obj) {
       
   262         this.linkResolvedObj = obj;
       
   263     }
       
   264 
       
   265     /**
       
   266      * Generates the string representation of this exception.
       
   267      * This string consists of the NamingException information plus
       
   268      * the link's remaining name.
       
   269      * This string is used for debugging and not meant to be interpreted
       
   270      * programmatically.
       
   271      * @return The non-null string representation of this link exception.
       
   272      */
       
   273     public String toString() {
       
   274         return super.toString() + "; Link Remaining Name: '" +
       
   275             this.linkRemainingName + "'";
       
   276     }
       
   277 
       
   278     /**
       
   279      * Generates the string representation of this exception.
       
   280      * This string consists of the NamingException information plus
       
   281      * the additional information of resolving the link.
       
   282      * If 'detail' is true, the string also contains information on
       
   283      * the link resolved object. If false, this method is the same
       
   284      * as the form of toString() that accepts no parameters.
       
   285      * This string is used for debugging and not meant to be interpreted
       
   286      * programmatically.
       
   287      *
       
   288      * @param   detail  If true, add information about the link resolved
       
   289      *                  object.
       
   290      * @return The non-null string representation of this link exception.
       
   291      */
       
   292     public String toString(boolean detail) {
       
   293         if (!detail || this.linkResolvedObj == null)
       
   294             return this.toString();
       
   295 
       
   296         return this.toString() + "; Link Resolved Object: " +
       
   297             this.linkResolvedObj;
       
   298     }
       
   299 
       
   300     /**
       
   301      * Use serialVersionUID from JNDI 1.1.1 for interoperability
       
   302      */
       
   303     private static final long serialVersionUID = -7967662604076777712L;
       
   304 };