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   {
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   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   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   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   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   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   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   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   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   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   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   name) {
206     if (name != null) {
207         this.linkResolvedName = (Name  )(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   name) {
231     if (name != null)
232         this.linkRemainingName = (Name  )(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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags