KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > LinkException


1 /*
2  * @(#)LinkException.java 1.8 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.naming;
9
10 /**
11  * This exception is used to describe problems encounter while resolving links.
12  * Addition information is added to the base NamingException for pinpointing
13  * the problem with the link.
14  *<p>
15  * Analogous to how NamingException captures name resolution information,
16  * LinkException captures "link"-name resolution information pinpointing
17  * the problem encountered while resolving a link. All these fields may
18  * be null.
19  * <ul>
20  * <li> Link Resolved Name. Portion of link name that has been resolved.
21  * <li> Link Resolved Object. Object to which resolution of link name proceeded.
22  * <li> Link Remaining Name. Portion of link name that has not been resolved.
23  * <li> Link Explanation. Detail explaining why link resolution failed.
24  *</ul>
25  *
26   *<p>
27   * A LinkException instance is not synchronized against concurrent
28   * multithreaded access. Multiple threads trying to access and modify
29   * a single LinkException instance should lock the object.
30   *
31   * @author Rosanna Lee
32   * @author Scott Seligman
33   * @version 1.8 03/12/19
34   *
35   * @see Context#lookupLink
36   * @see LinkRef
37   * @since 1.3
38   */

39
40
41   /*<p>
42   * The serialized form of a LinkException object consists of the
43   * serialized fields of its NamingException superclass, the link resolved
44   * name (a Name object), the link resolved object, link remaining name
45   * (a Name object), and the link explanation String.
46 */

47
48
49 public class LinkException extends NamingException JavaDoc {
50     /**
51      * Contains the part of the link that has been successfully resolved.
52      * It is a composite name and can be null.
53      * This field is initialized by the constructors.
54      * You should access and manipulate this field
55      * through its get and set methods.
56      * @serial
57      * @see #getLinkResolvedName
58      * @see #setLinkResolvedName
59      */

60     protected Name JavaDoc linkResolvedName;
61
62     /**
63       * Contains the object to which resolution of the part of the link was successful.
64       * Can be null. This field is initialized by the constructors.
65       * You should access and manipulate this field
66       * through its get and set methods.
67       * @serial
68       * @see #getLinkResolvedObj
69       * @see #setLinkResolvedObj
70       */

71     protected Object JavaDoc linkResolvedObj;
72
73     /**
74      * Contains the remaining link name that has not been resolved yet.
75      * It is a composite name and can be null.
76      * This field is initialized by the constructors.
77      * You should access and manipulate this field
78      * through its get and set methods.
79      * @serial
80      * @see #getLinkRemainingName
81      * @see #setLinkRemainingName
82      */

83     protected Name JavaDoc linkRemainingName;
84
85     /**
86      * Contains the exception of why resolution of the link failed.
87      * Can be null. This field is initialized by the constructors.
88      * You should access and manipulate this field
89      * through its get and set methods.
90      * @serial
91      * @see #getLinkExplanation
92      * @see #setLinkExplanation
93      */

94     protected String JavaDoc linkExplanation;
95
96     /**
97       * Constructs a new instance of LinkException with an explanation
98       * All the other fields are initialized to null.
99       * @param explanation A possibly null string containing additional
100       * detail about this exception.
101       * @see java.lang.Throwable#getMessage
102       */

103     public LinkException(String JavaDoc explanation) {
104     super(explanation);
105     linkResolvedName = null;
106     linkResolvedObj = null;
107     linkRemainingName = null;
108     linkExplanation = null;
109     }
110
111     /**
112       * Constructs a new instance of LinkException.
113       * All the non-link-related and link-related fields are initialized to null.
114       */

115     public LinkException() {
116     super();
117     linkResolvedName = null;
118     linkResolvedObj = null;
119     linkRemainingName = null;
120     linkExplanation = null;
121     }
122
123     /**
124      * Retrieves the leading portion of the link name that was resolved
125      * successfully.
126      *
127      * @return The part of the link name that was resolved successfully.
128      * It is a composite name. It can be null, which means
129      * the link resolved name field has not been set.
130      * @see #getLinkResolvedObj
131      * @see #setLinkResolvedName
132      */

133     public Name JavaDoc getLinkResolvedName() {
134     return this.linkResolvedName;
135     }
136
137     /**
138      * Retrieves the remaining unresolved portion of the link name.
139      * @return The part of the link name that has not been resolved.
140      * It is a composite name. It can be null, which means
141      * the link remaining name field has not been set.
142      * @see #setLinkRemainingName
143      */

144     public Name JavaDoc getLinkRemainingName() {
145     return this.linkRemainingName;
146     }
147
148     /**
149      * Retrieves the object to which resolution was successful.
150      * This is the object to which the resolved link name is bound.
151      *
152      * @return The possibly null object that was resolved so far.
153      * If null, it means the link resolved object field has not been set.
154      * @see #getLinkResolvedName
155      * @see #setLinkResolvedObj
156      */

157     public Object JavaDoc getLinkResolvedObj() {
158     return this.linkResolvedObj;
159     }
160
161     /**
162       * Retrieves the explanation associated with the problem encounter
163       * when resolving a link.
164       *
165       * @return The possibly null detail string explaining more about the problem
166       * with resolving a link.
167       * If null, it means there is no
168       * link detail message for this exception.
169       * @see #setLinkExplanation
170       */

171     public String JavaDoc getLinkExplanation() {
172     return this.linkExplanation;
173     }
174
175     /**
176       * Sets the explanation associated with the problem encounter
177       * when resolving a link.
178       *
179       * @param msg The possibly null detail string explaining more about the problem
180       * with resolving a link. If null, it means no detail will be recorded.
181       * @see #getLinkExplanation
182       */

183     public void setLinkExplanation(String JavaDoc msg) {
184     this.linkExplanation = msg;
185     }
186
187     /**
188      * Sets the resolved link name field of this exception.
189      *<p>
190      * <tt>name</tt> is a composite name. If the intent is to set
191      * this field using a compound name or string, you must
192      * "stringify" the compound name, and create a composite
193      * name with a single component using the string. You can then
194      * invoke this method using the resulting composite name.
195      *<p>
196      * A copy of <code>name</code> is made and stored.
197      * Subsequent changes to <code>name</code> does not
198      * affect the copy in this NamingException and vice versa.
199      *
200      *
201      * @param name The name to set resolved link name to. This can be null.
202      * If null, it sets the link resolved name field to null.
203      * @see #getLinkResolvedName
204      */

205     public void setLinkResolvedName(Name JavaDoc name) {
206     if (name != null) {
207         this.linkResolvedName = (Name JavaDoc)(name.clone());
208     } else {
209         this.linkResolvedName = null;
210     }
211     }
212
213     /**
214      * Sets the remaining link name field of this exception.
215      *<p>
216      * <tt>name</tt> is a composite name. If the intent is to set
217      * this field using a compound name or string, you must
218      * "stringify" the compound name, and create a composite
219      * name with a single component using the string. You can then
220      * invoke this method using the resulting composite name.
221      *<p>
222      * A copy of <code>name</code> is made and stored.
223      * Subsequent changes to <code>name</code> does not
224      * affect the copy in this NamingException and vice versa.
225      *
226      * @param name The name to set remaining link name to. This can be null.
227      * If null, it sets the remaining name field to null.
228      * @see #getLinkRemainingName
229      */

230     public void setLinkRemainingName(Name JavaDoc name) {
231     if (name != null)
232         this.linkRemainingName = (Name JavaDoc)(name.clone());
233     else
234         this.linkRemainingName = null;
235     }
236
237     /**
238      * Sets the link resolved object field of this exception.
239      * This indicates the last successfully resolved object of link name.
240      * @param obj The object to set link resolved object to. This can be null.
241      * If null, the link resolved object field is set to null.
242      * @see #getLinkResolvedObj
243      */

244     public void setLinkResolvedObj(Object JavaDoc obj) {
245     this.linkResolvedObj = obj;
246     }
247
248     /**
249      * Generates the string representation of this exception.
250      * This string consists of the NamingException information plus
251      * the link's remaining name.
252      * This string is used for debugging and not meant to be interpreted
253      * programmatically.
254      * @return The non-null string representation of this link exception.
255      */

256     public String JavaDoc toString() {
257     return super.toString() + "; Link Remaining Name: '" +
258         this.linkRemainingName + "'";
259     }
260
261     /**
262      * Generates the string representation of this exception.
263      * This string consists of the NamingException information plus
264      * the additional information of resolving the link.
265      * If 'detail' is true, the string also contains information on
266      * the link resolved object. If false, this method is the same
267      * as the form of toString() that accepts no parameters.
268      * This string is used for debugging and not meant to be interpreted
269      * programmatically.
270      *
271      * @param detail If true, add information about the link resolved
272      * object.
273      * @return The non-null string representation of this link exception.
274      */

275     public String JavaDoc toString(boolean detail) {
276     if (!detail || this.linkResolvedObj == null)
277         return this.toString();
278
279     return this.toString() + "; Link Resolved Object: " +
280         this.linkResolvedObj;
281     }
282
283     /**
284      * Use serialVersionUID from JNDI 1.1.1 for interoperability
285      */

286     private static final long serialVersionUID = -7967662604076777712L;
287 };
288
Popular Tags