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
26package 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
66public 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};
305