Home » openjdk-7 » javax » naming » [javadoc | source]

    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   }

Home » openjdk-7 » javax » naming » [javadoc | source]