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 };