1 /*
2 * Copyright 1999-2004 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 };
Save This Page