/*

 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.naming;

/**

 * This class represents the object name and class name pair of a binding

 * found in a context.

 *<p>

 * A context consists of name-to-object bindings.

 * The NameClassPair class represents the name and the

 * class of the bound object. It consists

 * of a name and a string representing the

 * package-qualified class name.

 *<p>

 * Use subclassing for naming systems that generate contents of

 * a name/class pair dynamically.

 *<p>

 * A NameClassPair instance is not synchronized against concurrent

 * access by multiple threads. Threads that need to access a NameClassPair

 * concurrently should synchronize amongst themselves and provide

 * the necessary locking.

 *

 * @author Rosanna Lee

 * @author Scott Seligman

 *

 * @see Context#list

 * @since 1.3

 */

 /*

  * <p>

  * The serialized form of a NameClassPair object consists of the name (a

  * String), class name (a String), and isRelative flag (a boolean).

  */

public class NameClassPair implements java.io.Serializable {

    /**

     * Contains the name of this NameClassPair.

     * It is initialized by the constructor and can be updated using

     * {@code setName()}.

     * @serial

     * @see #getName

     * @see #setName

     */

    private String name;

    /**

     *Contains the class name contained in this NameClassPair.

     * It is initialized by the constructor and can be updated using

     * {@code setClassName()}.

     * @serial

     * @see #getClassName

     * @see #setClassName

     */

    private String className;

    /**

     * Contains the full name of this NameClassPair within its

     * own namespace.

     * It is initialized using {@code setNameInNamespace()}

     * @serial

     * @see #getNameInNamespace

     * @see #setNameInNamespace

     */

    private String fullName = null;

    /**

     * Records whether the name of this {@code NameClassPair}

     * is relative to the target context.

     * It is initialized by the constructor and can be updated using

     * {@code setRelative()}.

     * @serial

     * @see #isRelative

     * @see #setRelative

     * @see #getName

     * @see #setName

     */

    private boolean isRel = true;

    /**

     * Constructs an instance of a NameClassPair given its

     * name and class name.

     *

     * @param   name    The non-null name of the object. It is relative

     *                  to the <em>target context</em> (which is

     * named by the first parameter of the <code>list()</code> method)

     * @param   className       The possibly null class name of the object

     *          bound to name. It is null if the object bound is null.

     * @see #getClassName

     * @see #setClassName

     * @see #getName

     * @see #setName

     */

    public NameClassPair(String name, String className) {

        this.name = name;

        this.className = className;

    }

    /**

     * Constructs an instance of a NameClassPair given its

     * name, class name, and whether it is relative to the listing context.

     *

     * @param   name    The non-null name of the object.

     * @param   className       The possibly null class name of the object

     *  bound to name.  It is null if the object bound is null.

     * @param isRelative true if <code>name</code> is a name relative

     *          to the target context (which is named by the first parameter

     *          of the <code>list()</code> method); false if <code>name</code>

     *          is a URL string.

     * @see #getClassName

     * @see #setClassName

     * @see #getName

     * @see #setName

     * @see #isRelative

     * @see #setRelative

     */

    public NameClassPair(String name, String className, boolean isRelative) {

        this.name = name;

        this.className = className;

        this.isRel = isRelative;

    }

    /**

     * Retrieves the class name of the object bound to the name of this binding.

     * If a reference or some other indirect information is bound,

     * retrieves the class name of the eventual object that

     * will be returned by {@code Binding.getObject()}.

     *

     * @return  The possibly null class name of object bound.

     *          It is null if the object bound is null.

     * @see Binding#getObject

     * @see Binding#getClassName

     * @see #setClassName

     */

    public String getClassName() {

        return className;

    }

    /**

     * Retrieves the name of this binding.

     * If {@code isRelative()} is true, this name is relative to the

     * target context (which is named by the first parameter of the

     * {@code list()}).

     * If {@code isRelative()} is false, this name is a URL string.

     *

     * @return  The non-null name of this binding.

     * @see #isRelative

     * @see #setName

     */

    public String getName() {

        return name;

    }

    /**

     * Sets the name of this binding.

     *

     * @param   name the non-null string to use as the name.

     * @see #getName

     * @see #setRelative

     */

    public void setName(String name) {

        this.name = name;

    }

    /**

     * Sets the class name of this binding.

     *

     * @param   name the possibly null string to use as the class name.

     * If null, {@code Binding.getClassName()} will return

     * the actual class name of the object in the binding.

     * The class name will be null if the object bound is null.

     * @see #getClassName

     * @see Binding#getClassName

     */

    public void setClassName(String name) {

        this.className = name;

    }

    /**

     * Determines whether the name of this binding is

     * relative to the target context (which is named by

     * the first parameter of the <code>list()</code> method).

     *

     * @return true if the name of this binding is relative to the

     *          target context;

     *          false if the name of this binding is a URL string.

     * @see #setRelative

     * @see #getName

     */

    public boolean isRelative() {

        return isRel;

    }

    /**

     * Sets whether the name of this binding is relative to the target

     * context (which is named by the first parameter of the <code>list()</code>

     * method).

     *

     * @param r If true, the name of binding is relative to the target context;

     *          if false, the name of binding is a URL string.

     * @see #isRelative

     * @see #setName

     */

    public void setRelative(boolean r) {

        isRel = r;

    }

    /**

     * Retrieves the full name of this binding.

     * The full name is the absolute name of this binding within

     * its own namespace. See {@link Context#getNameInNamespace()}.

     * <p>

     *

     * In naming systems for which the notion of full name does not

     * apply to this binding an {@code UnsupportedOperationException}

     * is thrown.

     * This exception is also thrown when a service provider written before

     * the introduction of the method is in use.

     * <p>

     * The string returned by this method is not a JNDI composite name and

     * should not be passed directly to context methods.

     *

     * @return The full name of this binding.

     * @throws UnsupportedOperationException if the notion of full name

     *         does not apply to this binding in the naming system.

     * @since 1.5

     * @see #setNameInNamespace

     * @see #getName

     */

    public String getNameInNamespace() {

        if (fullName == null) {

            throw new UnsupportedOperationException();

        }

        return fullName;

    }

    /**

     * Sets the full name of this binding.

     * This method must be called to set the full name whenever a

     * {@code NameClassPair} is created and a full name is

     * applicable to this binding.

     * <p>

     * Setting the full name to null, or not setting it at all, will

     * cause {@code getNameInNamespace()} to throw an exception.

     *

     * @param fullName The full name to use.

     * @since 1.5

     * @see #getNameInNamespace

     * @see #setName

     */

    public void setNameInNamespace(String fullName) {

        this.fullName = fullName;

    }

    /**

     * Generates the string representation of this name/class pair.

     * The string representation consists of the name and class name separated

     * by a colon (':').

     * The contents of this string is useful

     * for debugging and is not meant to be interpreted programmatically.

     *

     * @return The string representation of this name/class pair.

     */

    public String toString() {

        return (isRelative() ? "" : "(not relative)") + getName() + ": " +

                getClassName();

    }

    /**

     * Use serialVersionUID from JNDI 1.1.1 for interoperability

     */

    private static final long serialVersionUID = 5620776610160863339L;

}