classlib/modules/jndi/src/main/java/javax/naming/CannotProceedException.java

/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javax.naming;

import java.util.Hashtable;

/**
 * Naming operations throw a <code>CannotProceedException</code> when the
 * service provider context implementation is resolving a name but reaches a
 * name component that does not belong to the namespace of the current context.
 * <p>
 * The service provider is able to create a <code>CannotProceedException</code>
 * object and use methods on that object (including baseclass methods) to
 * provide full details of how far name resolution had progressed.
 * </p>
 * <p>
 * Typically, the methods used might include:
 * <ul>
 * <li><code>setEnvironment</code> to record the environment from the current
 * context</li>
 * <li> <code>setAltNameCtx</code> to record the current context</li>
 * <li> <code>setResolvedObj</code> to record the resolved object for the next
 * naming system</li>
 * <li> <code>setAltName</code> to record the name of the resolved object</li>
 * <li> <code>setRemainingName</code> to record the remaining unresolved name</li>
 * </ul>
 * </p>
 * <p>
 * If the incomplete naming operation is <code>rename</code>, the service
 * provider should also use the <code>setRemainingNewName</code> method to
 * record the unresolved part of the new name.
 * </p>
 * <p>
 * The service provider can pass the <code>CannotProceedException</code> as a
 * parameter to <code>NamingManager</code> methods such as
 * <code>getContinuationContext</code> to attempt to locate another service
 * provider for the next naming system. If successful, that service provider can
 * return a new <code>Context</code> object on which the naming operation can
 * proceed further. If unsuccessful, the <code>CannotProceedException</code>
 * can be thrown by the service provider so that the JNDI application can handle
 * it and take appropriate action.
 * </p>
 * <p>
 * Multithreaded access to a single <code>CannotProceedException</code>
 * instance is only safe when client code uses appropriate synchronization and
 * locking.
 * </p>
 * 
 */
public class CannotProceedException extends NamingException {

    /*
     * This constant is used during deserialization to check the version which
     * created the serialized object.
     */
    private final static long serialVersionUID = 1219724816191576813L;

    /**
     * Contains a composite name that is the name of the resolved object which
     * is relative to the context in <code>altNameCtx</code>. This field may
     * be null and is initially null. This field should be accessed and modified
     * using only <code>getAltName</code> and <code>setAltName</code>.
     */
    protected Name altName = null;

    /**
     * Contains the context to which the <code>altName</code> field is
     * relative. This field may be null and is initially null. A null value
     * implies the default initial context. This field should be accessed and
     * modified using only <code>getAltNameCtx</code> and
     * <code>setAltNameCtx</code>.
     */
    protected Context altNameCtx = null;

    /**
     * Contains the environment of the context in which name resolution for the
     * naming operation could not proceed further. Initially null. Should only
     * be manipulated using <code>getEnvironment</code> and
     * <code>setEnvironment methods</code>.
     */
    protected Hashtable<?, ?> environment = null;

    /**
     * Contains a composite name that is the unresolved part of the new name
     * that was specified in a <code>Context.rename</code> operation and may
     * be used to continue the <code>rename</code> operation. This field may
     * be null and is initially null. This field should be accessed and modified
     * using only <code>getRemainingNewName</code> and
     * <code>setRemainingNewName</code>.
     */
    protected Name remainingNewName = null;

    /**
     * Constructs a <code>CannotProceedException</code> object. All
     * unspecified fields are initialized to null.
     */
    public CannotProceedException() {
        super();
    }

    /**
     * Constructs a <code>CannotProceedException</code> object with an
     * optionally specified <code>String</code> parameter containing a
     * detailed explanation message. The <code>String</code> parameter may be
     * null. All unspecified fields are initialized to null.
     * 
     * @param s
     *            The detailed explanation message for the exception. It may be
     *            null.
     */
    public CannotProceedException(String s) {
        super(s);
    }

    /**
     * Retrieves the value of the <code>altName</code> field.
     * 
     * @return the value of the <code>altName</code> field.
     * @see javax.naming.spi.ObjectFactory#getObjectInstance(Object, Name,
     *      Context, Hashtable)
     */
    public Name getAltName() {
        return altName;
    }

    /**
     * Retrieves the value of the <code>altNameCtx</code> field.
     * 
     * @return the value of the <code>altNameCtx</code> field.
     * @see javax.naming.spi.ObjectFactory#getObjectInstance(Object, Name,
     *      Context, Hashtable)
     */
    public Context getAltNameCtx() {
        return altNameCtx;
    }

    /**
     * Retrieves the value of the protected field <code>environment</code>
     * which may be null.
     * 
     * @return the value of the protected field <code>environment</code> which
     *         may be null.
     */
    public Hashtable<?, ?> getEnvironment() {
        return environment;
    }

    /**
     * Retrieves the value of the <code>remainingNewName</code> field.
     * 
     * @return the value of the <code>remainingNewName</code> field.
     */
    public Name getRemainingNewName() {
        return remainingNewName;
    }

    /**
     * Modifies the value of the <code>altName</code> field to the specified
     * <code>Name</code> parameter which is a composite name and may be null.
     * 
     * @param name
     *            the name to set.
     */
    public void setAltName(Name name) {
        altName = name;
    }

    /**
     * Modifies the value of the <code>altNameCtx</code> field to the
     * specified <code>Context</code> parameter which may be null.
     * 
     * @param context
     *            the new context to set.
     */
    public void setAltNameCtx(Context context) {
        altNameCtx = context;
    }

    /**
     * Sets the value of the protected field <code>environment</code> from the
     * <code>environment</code> parameter which may be null.
     * 
     * @param hashtable
     *            the new environment to set.
     */
    public void setEnvironment(Hashtable<?, ?> hashtable) {
        environment = hashtable;
    }

    /**
     * Modifies the value of the <code>remainingNewName</code> field to the
     * specified parameter which may be null. But otherwise is a composite name.
     * When needing to specify other names, first convert them into a composite
     * name with a single component, and then specify that composite name when
     * invoking this method.
     * <p>
     * When a non-null name is specified, a clone of the composite name is
     * stored in the <code>remainingNewName</code> field that becomes
     * independent of the specified name.
     * </p>
     * 
     * @param name
     *            the new name to set.
     */
    public void setRemainingNewName(Name name) {
        remainingNewName = (null == name) ? null : (Name) name.clone();
    }

}