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