View Javadoc
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  
26  package 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  
59  public 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       * <tt>setName()</tt>.
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       * <tt>setClassName()</tt>.
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 <tt>setNameInNamespace()</tt>
84       * @serial
85       * @see #getNameInNamespace
86       * @see #setNameInNamespace
87       */
88      private String fullName = null;
89  
90  
91      /**
92       * Records whether the name of this <tt>NameClassPair</tt>
93       * is relative to the target context.
94       * It is initialized by the constructor and can be updated using
95       * <tt>setRelative()</tt>.
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 <tt>Binding.getObject()</tt>.
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 <tt>isRelative()</tt> is true, this name is relative to the
166      * target context (which is named by the first parameter of the
167      * <tt>list()</tt>).
168      * If <tt>isRelative()</tt> 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, <tt>Binding.getClassName()</tt> 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 <tt>UnsupportedOperationException</tt>
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      * <tt>NameClassPair</tt> 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 <tt>getNameInNamespace()</tt> 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 }