src/share/classes/javax/naming/LinkException.java

Print this page




   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


  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;


 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      */




   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


  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;


 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      * <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> 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      * <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> 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      */