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      * {@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 }