001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming;
027
028 /**
029 * This class represents the object name and class name pair of a binding
030 * found in a context.
031 *<p>
032 * A context consists of name-to-object bindings.
033 * The NameClassPair class represents the name and the
034 * class of the bound object. It consists
035 * of a name and a string representing the
036 * package-qualified class name.
037 *<p>
038 * Use subclassing for naming systems that generate contents of
039 * a name/class pair dynamically.
040 *<p>
041 * A NameClassPair instance is not synchronized against concurrent
042 * access by multiple threads. Threads that need to access a NameClassPair
043 * concurrently should synchronize amongst themselves and provide
044 * the necessary locking.
045 *
046 * @author Rosanna Lee
047 * @author Scott Seligman
048 * @version 1.17 07/05/05
049 *
050 * @see Context#list
051 * @since 1.3
052 */
053
054 /*
055 * <p>
056 * The serialized form of a NameClassPair object consists of the name (a
057 * String), class name (a String), and isRelative flag (a boolean).
058 */
059
060 public class NameClassPair implements java.io.Serializable {
061 /**
062 * Contains the name of this NameClassPair.
063 * It is initialized by the constructor and can be updated using
064 * <tt>setName()</tt>.
065 * @serial
066 * @see #getName
067 * @see #setName
068 */
069 private String name;
070
071 /**
072 *Contains the class name contained in this NameClassPair.
073 * It is initialized by the constructor and can be updated using
074 * <tt>setClassName()</tt>.
075 * @serial
076 * @see #getClassName
077 * @see #setClassName
078 */
079 private String className;
080
081 /**
082 * Contains the full name of this NameClassPair within its
083 * own namespace.
084 * It is initialized using <tt>setNameInNamespace()</tt>
085 * @serial
086 * @see #getNameInNamespace
087 * @see #setNameInNamespace
088 */
089 private String fullName = null;
090
091 /**
092 * Records whether the name of this <tt>NameClassPair</tt>
093 * is relative to the target context.
094 * It is initialized by the constructor and can be updated using
095 * <tt>setRelative()</tt>.
096 * @serial
097 * @see #isRelative
098 * @see #setRelative
099 * @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,
142 boolean isRelative) {
143 this .name = name;
144 this .className = className;
145 this .isRel = isRelative;
146 }
147
148 /**
149 * Retrieves the class name of the object bound to the name of this binding.
150 * If a reference or some other indirect information is bound,
151 * retrieves the class name of the eventual object that
152 * will be returned by <tt>Binding.getObject()</tt>.
153 *
154 * @return The possibly null class name of object bound.
155 * It is null if the object bound is null.
156 * @see Binding#getObject
157 * @see Binding#getClassName
158 * @see #setClassName
159 */
160 public String getClassName() {
161 return className;
162 }
163
164 /**
165 * Retrieves the name of this binding.
166 * If <tt>isRelative()</tt> is true, this name is relative to the
167 * target context (which is named by the first parameter of the
168 * <tt>list()</tt>).
169 * If <tt>isRelative()</tt> is false, this name is a URL string.
170 *
171 * @return The non-null name of this binding.
172 * @see #isRelative
173 * @see #setName
174 */
175 public String getName() {
176 return name;
177 }
178
179 /**
180 * Sets the name of this binding.
181 *
182 * @param name the non-null string to use as the name.
183 * @see #getName
184 * @see #setRelative
185 */
186 public void setName(String name) {
187 this .name = name;
188 }
189
190 /**
191 * Sets the class name of this binding.
192 *
193 * @param name the possibly null string to use as the class name.
194 * If null, <tt>Binding.getClassName()</tt> will return
195 * the actual class name of the object in the binding.
196 * The class name will be null if the object bound is null.
197 * @see #getClassName
198 * @see Binding#getClassName
199 */
200 public void setClassName(String name) {
201 this .className = name;
202 }
203
204 /**
205 * Determines whether the name of this binding is
206 * relative to the target context (which is named by
207 * the first parameter of the <code>list()</code> method).
208 *
209 * @return true if the name of this binding is relative to the
210 * target context;
211 * false if the name of this binding is a URL string.
212 * @see #setRelative
213 * @see #getName
214 */
215 public boolean isRelative() {
216 return isRel;
217 }
218
219 /**
220 * Sets whether the name of this binding is relative to the target
221 * context (which is named by the first parameter of the <code>list()</code>
222 * method).
223 *
224 * @param r If true, the name of binding is relative to the target context;
225 * if false, the name of binding is a URL string.
226 * @see #isRelative
227 * @see #setName
228 */
229 public void setRelative(boolean r) {
230 isRel = r;
231 }
232
233 /**
234 * Retrieves the full name of this binding.
235 * The full name is the absolute name of this binding within
236 * its own namespace. See {@link Context#getNameInNamespace()}.
237 * <p>
238 *
239 * In naming systems for which the notion of full name does not
240 * apply to this binding an <tt>UnsupportedOperationException</tt>
241 * is thrown.
242 * This exception is also thrown when a service provider written before
243 * the introduction of the method is in use.
244 * <p>
245 * The string returned by this method is not a JNDI composite name and
246 * should not be passed directly to context methods.
247 *
248 * @return The full name of this binding.
249 * @throws UnsupportedOperationException if the notion of full name
250 * does not apply to this binding in the naming system.
251 * @since 1.5
252 * @see #setNameInNamespace
253 * @see #getName
254 */
255 public String getNameInNamespace() {
256 if (fullName == null) {
257 throw new UnsupportedOperationException();
258 }
259 return fullName;
260 }
261
262 /**
263 * Sets the full name of this binding.
264 * This method must be called to set the full name whenever a
265 * <tt>NameClassPair</tt> is created and a full name is
266 * applicable to this binding.
267 * <p>
268 * Setting the full name to null, or not setting it at all, will
269 * cause <tt>getNameInNamespace()</tt> to throw an exception.
270 *
271 * @param fullName The full name to use.
272 * @since 1.5
273 * @see #getNameInNamespace
274 * @see #setName
275 */
276 public void setNameInNamespace(String fullName) {
277 this .fullName = fullName;
278 }
279
280 /**
281 * Generates the string representation of this name/class pair.
282 * The string representation consists of the name and class name separated
283 * by a colon (':').
284 * The contents of this string is useful
285 * for debugging and is not meant to be interpreted programmatically.
286 *
287 * @return The string representation of this name/class pair.
288 */
289 public String toString() {
290 return (isRelative() ? "" : "(not relative)") + getName()
291 + ": " + getClassName();
292 }
293
294 /**
295 * Use serialVersionUID from JNDI 1.1.1 for interoperability
296 */
297 private static final long serialVersionUID = 5620776610160863339L;
298 }
|