1/*
2 * Copyright (c) 1999, 2003, 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 class represents the object name and class name pair of a binding
30 * found in a context.
31 *<p>
32 * A context consists of name-to-object bindings.
33 * The NameClassPair class represents the name and the
34 * class of the bound object. It consists
35 * of a name and a string representing the
36 * package-qualified class name.
37 *<p>
38 * Use subclassing for naming systems that generate contents of
39 * a name/class pair dynamically.
40 *<p>
41 * A NameClassPair instance is not synchronized against concurrent
42 * access by multiple threads. Threads that need to access a NameClassPair
43 * concurrently should synchronize amongst themselves and provide
44 * the necessary locking.
45 *
46 * @author Rosanna Lee
47 * @author Scott Seligman
48 *
49 * @see Context#list
50 * @since 1.3
51 */
52
53 /*
54  * <p>
55  * The serialized form of a NameClassPair object consists of the name (a
56  * String), class name (a String), and isRelative flag (a boolean).
57  */
58
59public class NameClassPair implements java.io.Serializable {
60    /**
61     * Contains the name of this NameClassPair.
62     * It is initialized by the constructor and can be updated using
63     * {@code setName()}.
64     * @serial
65     * @see #getName
66     * @see #setName
67     */
68    private String name;
69
70    /**
71     *Contains the class name contained in this NameClassPair.
72     * It is initialized by the constructor and can be updated using
73     * {@code setClassName()}.
74     * @serial
75     * @see #getClassName
76     * @see #setClassName
77     */
78    private String className;
79
80    /**
81     * Contains the full name of this NameClassPair within its
82     * own namespace.
83     * It is initialized using {@code setNameInNamespace()}
84     * @serial
85     * @see #getNameInNamespace
86     * @see #setNameInNamespace
87     */
88    private String fullName = null;
89
90
91    /**
92     * Records whether the name of this {@code NameClassPair}
93     * is relative to the target context.
94     * It is initialized by the constructor and can be updated using
95     * {@code setRelative()}.
96     * @serial
97     * @see #isRelative
98     * @see #setRelative
99     * @see #getName
100     * @see #setName
101     */
102    private boolean isRel = true;
103
104    /**
105     * Constructs an instance of a NameClassPair given its
106     * name and class name.
107     *
108     * @param   name    The non-null name of the object. It is relative
109     *                  to the <em>target context</em> (which is
110     * named by the first parameter of the <code>list()</code> method)
111     * @param   className       The possibly null class name of the object
112     *          bound to name. It is null if the object bound is null.
113     * @see #getClassName
114     * @see #setClassName
115     * @see #getName
116     * @see #setName
117     */
118    public NameClassPair(String name, String className) {
119        this.name = name;
120        this.className = className;
121    }
122
123    /**
124     * Constructs an instance of a NameClassPair given its
125     * name, class name, and whether it is relative to the listing context.
126     *
127     * @param   name    The non-null name of the object.
128     * @param   className       The possibly null class name of the object
129     *  bound to name.  It is null if the object bound is null.
130     * @param isRelative true if <code>name</code> is a name relative
131     *          to the target context (which is named by the first parameter
132     *          of the <code>list()</code> method); false if <code>name</code>
133     *          is a URL string.
134     * @see #getClassName
135     * @see #setClassName
136     * @see #getName
137     * @see #setName
138     * @see #isRelative
139     * @see #setRelative
140     */
141    public NameClassPair(String name, String className, boolean isRelative) {
142        this.name = name;
143        this.className = className;
144        this.isRel = isRelative;
145    }
146
147    /**
148     * Retrieves the class name of the object bound to the name of this binding.
149     * If a reference or some other indirect information is bound,
150     * retrieves the class name of the eventual object that
151     * will be returned by {@code Binding.getObject()}.
152     *
153     * @return  The possibly null class name of object bound.
154     *          It is null if the object bound is null.
155     * @see Binding#getObject
156     * @see Binding#getClassName
157     * @see #setClassName
158     */
159    public String getClassName() {
160        return className;
161    }
162
163    /**
164     * Retrieves the name of this binding.
165     * If {@code isRelative()} is true, this name is relative to the
166     * target context (which is named by the first parameter of the
167     * {@code list()}).
168     * If {@code isRelative()} is false, this name is a URL string.
169     *
170     * @return  The non-null name of this binding.
171     * @see #isRelative
172     * @see #setName
173     */
174    public String getName() {
175        return name;
176    }
177
178    /**
179     * Sets the name of this binding.
180     *
181     * @param   name the non-null string to use as the name.
182     * @see #getName
183     * @see #setRelative
184     */
185    public void setName(String name) {
186        this.name = name;
187    }
188
189    /**
190     * Sets the class name of this binding.
191     *
192     * @param   name the possibly null string to use as the class name.
193     * If null, {@code Binding.getClassName()} will return
194     * the actual class name of the object in the binding.
195     * The class name will be null if the object bound is null.
196     * @see #getClassName
197     * @see Binding#getClassName
198     */
199    public void setClassName(String name) {
200        this.className = name;
201    }
202
203    /**
204     * Determines whether the name of this binding is
205     * relative to the target context (which is named by
206     * the first parameter of the <code>list()</code> method).
207     *
208     * @return true if the name of this binding is relative to the
209     *          target context;
210     *          false if the name of this binding is a URL string.
211     * @see #setRelative
212     * @see #getName
213     */
214    public boolean isRelative() {
215        return isRel;
216    }
217
218    /**
219     * Sets whether the name of this binding is relative to the target
220     * context (which is named by the first parameter of the <code>list()</code>
221     * method).
222     *
223     * @param r If true, the name of binding is relative to the target context;
224     *          if false, the name of binding is a URL string.
225     * @see #isRelative
226     * @see #setName
227     */
228    public void setRelative(boolean r) {
229        isRel = r;
230    }
231
232    /**
233     * Retrieves the full name of this binding.
234     * The full name is the absolute name of this binding within
235     * its own namespace. See {@link Context#getNameInNamespace()}.
236     * <p>
237     *
238     * In naming systems for which the notion of full name does not
239     * apply to this binding an {@code UnsupportedOperationException}
240     * is thrown.
241     * This exception is also thrown when a service provider written before
242     * the introduction of the method is in use.
243     * <p>
244     * The string returned by this method is not a JNDI composite name and
245     * should not be passed directly to context methods.
246     *
247     * @return The full name of this binding.
248     * @throws UnsupportedOperationException if the notion of full name
249     *         does not apply to this binding in the naming system.
250     * @since 1.5
251     * @see #setNameInNamespace
252     * @see #getName
253     */
254    public String getNameInNamespace() {
255        if (fullName == null) {
256            throw new UnsupportedOperationException();
257        }
258        return fullName;
259    }
260
261    /**
262     * Sets the full name of this binding.
263     * This method must be called to set the full name whenever a
264     * {@code NameClassPair} is created and a full name is
265     * applicable to this binding.
266     * <p>
267     * Setting the full name to null, or not setting it at all, will
268     * cause {@code getNameInNamespace()} to throw an exception.
269     *
270     * @param fullName The full name to use.
271     * @since 1.5
272     * @see #getNameInNamespace
273     * @see #setName
274     */
275    public void setNameInNamespace(String fullName) {
276        this.fullName = fullName;
277    }
278
279    /**
280     * Generates the string representation of this name/class pair.
281     * The string representation consists of the name and class name separated
282     * by a colon (':').
283     * The contents of this string is useful
284     * for debugging and is not meant to be interpreted programmatically.
285     *
286     * @return The string representation of this name/class pair.
287     */
288    public String toString() {
289        return (isRelative() ? "" : "(not relative)") + getName() + ": " +
290                getClassName();
291    }
292
293
294    /**
295     * Use serialVersionUID from JNDI 1.1.1 for interoperability
296     */
297    private static final long serialVersionUID = 5620776610160863339L;
298}
299