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 encounter while resolving links.
  30  * Addition information is added to the base NamingException for pinpointing
  31  * the problem with the link.
  32  *<p>
  33  * Analogous 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 encounter
 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 encounter
 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      * <tt>name</tt> 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> does 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      * <tt>name</tt> 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> does 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 };