1 /*
2 * Copyright (c) 1999, 2019, 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 @SuppressWarnings("serial") // Not statically typed as Serializable
89 protected Object linkResolvedObj;
90
91 /**
92 * Contains the remaining link name that has not been resolved yet.
93 * It is a composite name and can be null.
94 * This field is initialized by the constructors.
95 * You should access and manipulate this field
96 * through its get and set methods.
97 * @serial
98 * @see #getLinkRemainingName
99 * @see #setLinkRemainingName
100 */
101 protected Name linkRemainingName;
102
103 /**
104 * Contains the exception of why resolution of the link failed.
105 * Can be null. This field is initialized by the constructors.
106 * You should access and manipulate this field
107 * through its get and set methods.
108 * @serial
109 * @see #getLinkExplanation
110 * @see #setLinkExplanation
111 */
112 protected String linkExplanation;
113
114 /**
115 * Constructs a new instance of LinkException with an explanation.
116 * All the other fields are initialized to null.
117 * @param explanation A possibly null string containing additional
118 * detail about this exception.
119 * @see java.lang.Throwable#getMessage
120 */
121 public LinkException(String explanation) {
122 super(explanation);
123 linkResolvedName = null;
124 linkResolvedObj = null;
125 linkRemainingName = null;
126 linkExplanation = null;
127 }
128
129 /**
130 * Constructs a new instance of LinkException.
131 * All the non-link-related and link-related fields are initialized to null.
132 */
133 public LinkException() {
134 super();
135 linkResolvedName = null;
136 linkResolvedObj = null;
137 linkRemainingName = null;
138 linkExplanation = null;
139 }
140
141 /**
142 * Retrieves the leading portion of the link name that was resolved
143 * successfully.
144 *
145 * @return The part of the link name that was resolved successfully.
146 * It is a composite name. It can be null, which means
147 * the link resolved name field has not been set.
148 * @see #getLinkResolvedObj
149 * @see #setLinkResolvedName
150 */
151 public Name getLinkResolvedName() {
152 return this.linkResolvedName;
153 }
154
155 /**
156 * Retrieves the remaining unresolved portion of the link name.
157 * @return The part of the link name that has not been resolved.
158 * It is a composite name. It can be null, which means
159 * the link remaining name field has not been set.
160 * @see #setLinkRemainingName
161 */
162 public Name getLinkRemainingName() {
163 return this.linkRemainingName;
164 }
165
166 /**
167 * Retrieves the object to which resolution was successful.
168 * This is the object to which the resolved link name is bound.
169 *
170 * @return The possibly null object that was resolved so far.
171 * If null, it means the link resolved object field has not been set.
172 * @see #getLinkResolvedName
173 * @see #setLinkResolvedObj
174 */
175 public Object getLinkResolvedObj() {
176 return this.linkResolvedObj;
177 }
178
179 /**
180 * Retrieves the explanation associated with the problem encountered
181 * when resolving a link.
182 *
183 * @return The possibly null detail string explaining more about the problem
184 * with resolving a link.
185 * If null, it means there is no
186 * link detail message for this exception.
187 * @see #setLinkExplanation
188 */
189 public String getLinkExplanation() {
190 return this.linkExplanation;
191 }
192
193 /**
194 * Sets the explanation associated with the problem encountered
195 * when resolving a link.
196 *
197 * @param msg The possibly null detail string explaining more about the problem
198 * with resolving a link. If null, it means no detail will be recorded.
199 * @see #getLinkExplanation
200 */
201 public void setLinkExplanation(String msg) {
202 this.linkExplanation = msg;
203 }
204
205 /**
206 * Sets the resolved link name field of this exception.
207 *<p>
208 * {@code name} is a composite name. If the intent is to set
209 * this field using a compound name or string, you must
210 * "stringify" the compound name, and create a composite
211 * name with a single component using the string. You can then
212 * invoke this method using the resulting composite name.
213 *<p>
214 * A copy of <code>name</code> is made and stored.
215 * Subsequent changes to <code>name</code> do not
216 * affect the copy in this NamingException and vice versa.
217 *
218 *
219 * @param name The name to set resolved link name to. This can be null.
220 * If null, it sets the link resolved name field to null.
221 * @see #getLinkResolvedName
222 */
223 public void setLinkResolvedName(Name name) {
224 if (name != null) {
225 this.linkResolvedName = (Name)(name.clone());
226 } else {
227 this.linkResolvedName = null;
228 }
229 }
230
231 /**
232 * Sets the remaining link name field of this exception.
233 *<p>
234 * {@code name} is a composite name. If the intent is to set
235 * this field using a compound name or string, you must
236 * "stringify" the compound name, and create a composite
237 * name with a single component using the string. You can then
238 * invoke this method using the resulting composite name.
239 *<p>
240 * A copy of <code>name</code> is made and stored.
241 * Subsequent changes to <code>name</code> do not
242 * affect the copy in this NamingException and vice versa.
243 *
244 * @param name The name to set remaining link name to. This can be null.
245 * If null, it sets the remaining name field to null.
246 * @see #getLinkRemainingName
247 */
248 public void setLinkRemainingName(Name name) {
249 if (name != null)
250 this.linkRemainingName = (Name)(name.clone());
251 else
252 this.linkRemainingName = null;
253 }
254
255 /**
256 * Sets the link resolved object field of this exception.
257 * This indicates the last successfully resolved object of link name.
258 * @param obj The object to set link resolved object to. This can be null.
259 * If null, the link resolved object field is set to null.
260 * @see #getLinkResolvedObj
261 */
262 public void setLinkResolvedObj(Object obj) {
263 this.linkResolvedObj = obj;
264 }
265
266 /**
267 * Generates the string representation of this exception.
268 * This string consists of the NamingException information plus
269 * the link's remaining name.
270 * This string is used for debugging and not meant to be interpreted
271 * programmatically.
272 * @return The non-null string representation of this link exception.
273 */
274 public String toString() {
275 return super.toString() + "; Link Remaining Name: '" +
276 this.linkRemainingName + "'";
277 }
278
279 /**
280 * Generates the string representation of this exception.
281 * This string consists of the NamingException information plus
282 * the additional information of resolving the link.
283 * If 'detail' is true, the string also contains information on
284 * the link resolved object. If false, this method is the same
285 * as the form of toString() that accepts no parameters.
286 * This string is used for debugging and not meant to be interpreted
287 * programmatically.
288 *
289 * @param detail If true, add information about the link resolved
290 * object.
291 * @return The non-null string representation of this link exception.
292 */
293 public String toString(boolean detail) {
294 if (!detail || this.linkResolvedObj == null)
295 return this.toString();
296
297 return this.toString() + "; Link Resolved Object: " +
298 this.linkResolvedObj;
299 }
300
301 /**
302 * Use serialVersionUID from JNDI 1.1.1 for interoperability
303 */
304 private static final long serialVersionUID = -7967662604076777712L;
305 };