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       */
LinkException(String explanation)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       */
LinkException()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      */
getLinkResolvedName()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      */
getLinkRemainingName()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      */
getLinkResolvedObj()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       */
getLinkExplanation()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       */
setLinkExplanation(String msg)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      */
setLinkResolvedName(Name name)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      */
setLinkRemainingName(Name name)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      */
setLinkResolvedObj(Object obj)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      */
toString()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      */
toString(boolean detail)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 };
305