1 /*

     2  * Copyright (c) 1999, 2004, 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 import java.util.Hashtable;

    29 

    30 /**

    31   * This exception is thrown to indicate that the operation reached

    32   * a point in the name where the operation cannot proceed any further.

    33   * When performing an operation on a composite name, a naming service

    34   * provider may reach a part of the name that does not belong to its

    35   * namespace.  At that point, it can construct a

    36   * CannotProceedException and then invoke methods provided by

    37   * javax.naming.spi.NamingManager (such as getContinuationContext())

    38   * to locate another provider to continue the operation.  If this is

    39   * not possible, this exception is raised to the caller of the

    40   * context operation.

    41   *<p>

    42   * If the program wants to handle this exception in particular, it

    43   * should catch CannotProceedException explicitly before attempting to

    44   * catch NamingException.

    45   *<p>

    46   * A CannotProceedException instance is not synchronized against concurrent

    47   * multithreaded access. Multiple threads trying to access and modify

    48   * CannotProceedException should lock the object.

    49   *

    50   * @author Rosanna Lee

    51   * @author Scott Seligman

    52   * @since 1.3

    53   */

    54 

    55 /*

    56   * The serialized form of a CannotProceedException object consists of

    57   * the serialized fields of its NamingException superclass, the remaining new

    58   * name (a Name object), the environment (a Hashtable), the altName field

    59   * (a Name object), and the serialized form of the altNameCtx field.

    60   */

    61 

    62 

    63 public class CannotProceedException extends NamingException {

    64     /**

    65      * Contains the remaining unresolved part of the second

    66      * "name" argument to Context.rename().

    67      * This information is necessary for

    68      * continuing the Context.rename() operation.

    69      * <p>

    70      * This field is initialized to null.

    71      * It should not be manipulated directly:  it should

    72      * be accessed and updated using getRemainingName() and setRemainingName().

    73      * @serial

    74      *

    75      * @see #getRemainingNewName

    76      * @see #setRemainingNewName

    77      */

    78     protected Name remainingNewName = null;

    79 

    80     /**

    81      * Contains the environment

    82      * relevant for the Context or DirContext method that cannot proceed.

    83      * <p>

    84      * This field is initialized to null.

    85      * It should not be manipulated directly:  it should be accessed

    86      * and updated using getEnvironment() and setEnvironment().

    87      * @serial

    88      *

    89      * @see #getEnvironment

    90      * @see #setEnvironment

    91      */

    92     protected Hashtable<?,?> environment = null;

    93 

    94     /**

    95      * Contains the name of the resolved object, relative

    96      * to the context <code>altNameCtx</code>.  It is a composite name.

    97      * If null, then no name is specified.

    98      * See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>

    99      * method for details on how this is used.

   100      * <p>

   101      * This field is initialized to null.

   102      * It should not be manipulated directly:  it should

   103      * be accessed and updated using getAltName() and setAltName().

   104      * @serial

   105      *

   106      * @see #getAltName

   107      * @see #setAltName

   108      * @see #altNameCtx

   109      * @see javax.naming.spi.ObjectFactory#getObjectInstance

   110      */

   111     protected Name altName = null;

   112 

   113     /**

   114      * Contains the context relative to which

   115      * <code>altName</code> is specified.  If null, then the default initial

   116      * context is implied.

   117      * See the <code>javax.naming.spi.ObjectFactory.getObjectInstance</code>

   118      * method for details on how this is used.

   119      * <p>

   120      * This field is initialized to null.

   121      * It should not be manipulated directly:  it should

   122      * be accessed and updated using getAltNameCtx() and setAltNameCtx().

   123      * @serial

   124      *

   125      * @see #getAltNameCtx

   126      * @see #setAltNameCtx

   127      * @see #altName

   128      * @see javax.naming.spi.ObjectFactory#getObjectInstance

   129      */

   130     protected Context altNameCtx = null;

   131 

   132     /**

   133      * Constructs a new instance of CannotProceedException using an

   134      * explanation. All unspecified fields default to null.

   135      *

   136      * @param   explanation     A possibly null string containing additional

   137      *                          detail about this exception.

   138      *   If null, this exception has no detail message.

   139      * @see java.lang.Throwable#getMessage

   140      */

   141     public CannotProceedException(String explanation) {

   142         super(explanation);

   143     }

   144 

   145     /**

   146       * Constructs a new instance of CannotProceedException.

   147       * All fields default to null.

   148       */

   149     public CannotProceedException() {

   150         super();

   151     }

   152 

   153     /**

   154      * Retrieves the environment that was in effect when this exception

   155      * was created.

   156      * @return Possibly null environment property set.

   157      *          null means no environment was recorded for this exception.

   158      * @see #setEnvironment

   159      */

   160     public Hashtable<?,?> getEnvironment() {

   161         return environment;

   162     }

   163 

   164     /**

   165      * Sets the environment that will be returned when getEnvironment()

   166      * is called.

   167      * @param environment A possibly null environment property set.

   168      *          null means no environment is being recorded for

   169      *          this exception.

   170      * @see #getEnvironment

   171      */

   172     public void setEnvironment(Hashtable<?,?> environment) {

   173         this.environment = environment; // %%% clone it??

   174     }

   175 

   176     /**

   177      * Retrieves the "remaining new name" field of this exception, which is

   178      * used when this exception is thrown during a rename() operation.

   179      *

   180      * @return The possibly null part of the new name that has not been resolved.

   181      *          It is a composite name. It can be null, which means

   182      *          the remaining new name field has not been set.

   183      *

   184      * @see #setRemainingNewName

   185      */

   186     public Name getRemainingNewName() {

   187         return remainingNewName;

   188     }

   189 

   190     /**

   191      * Sets the "remaining new name" field of this exception.

   192      * This is the value returned by <code>getRemainingNewName()</code>.

   193      *<p>

   194      * <tt>newName</tt> is a composite name. If the intent is to set

   195      * this field using a compound name or string, you must

   196      * "stringify" the compound name, and create a composite

   197      * name with a single component using the string. You can then

   198      * invoke this method using the resulting composite name.

   199      *<p>

   200      * A copy of <code>newName</code> is made and stored.

   201      * Subsequent changes to <code>name</code> does not

   202      * affect the copy in this NamingException and vice versa.

   203      *

   204      * @param newName The possibly null name to set the "remaining new name" to.

   205      *          If null, it sets the remaining name field to null.

   206      *

   207      * @see #getRemainingNewName

   208      */

   209     public void setRemainingNewName(Name newName) {

   210         if (newName != null)

   211             this.remainingNewName = (Name)(newName.clone());

   212         else

   213             this.remainingNewName = null;

   214     }

   215 

   216     /**

   217      * Retrieves the <code>altName</code> field of this exception.

   218      * This is the name of the resolved object, relative to the context

   219      * <code>altNameCtx</code>. It will be used during a subsequent call to the

   220      * <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.

   221      *

   222      * @return The name of the resolved object, relative to

   223      *          <code>altNameCtx</code>.

   224      *          It is a composite name.  If null, then no name is specified.

   225      *

   226      * @see #setAltName

   227      * @see #getAltNameCtx

   228      * @see javax.naming.spi.ObjectFactory#getObjectInstance

   229      */

   230     public Name getAltName() {

   231         return altName;

   232     }

   233 

   234     /**

   235      * Sets the <code>altName</code> field of this exception.

   236      *

   237      * @param altName   The name of the resolved object, relative to

   238      *                  <code>altNameCtx</code>.

   239      *                  It is a composite name.

   240      *                  If null, then no name is specified.

   241      *

   242      * @see #getAltName

   243      * @see #setAltNameCtx

   244      */

   245     public void setAltName(Name altName) {

   246         this.altName = altName;

   247     }

   248 

   249     /**

   250      * Retrieves the <code>altNameCtx</code> field of this exception.

   251      * This is the context relative to which <code>altName</code> is named.

   252      * It will be used during a subsequent call to the

   253      * <code>javax.naming.spi.ObjectFactory.getObjectInstance</code> method.

   254      *

   255      * @return  The context relative to which <code>altName</code> is named.

   256      *          If null, then the default initial context is implied.

   257      *

   258      * @see #setAltNameCtx

   259      * @see #getAltName

   260      * @see javax.naming.spi.ObjectFactory#getObjectInstance

   261      */

   262     public Context getAltNameCtx() {

   263         return altNameCtx;

   264     }

   265 

   266     /**

   267      * Sets the <code>altNameCtx</code> field of this exception.

   268      *

   269      * @param altNameCtx

   270      *                  The context relative to which <code>altName</code>

   271      *                  is named.  If null, then the default initial context

   272      *                  is implied.

   273      *

   274      * @see #getAltNameCtx

   275      * @see #setAltName

   276      */

   277     public void setAltNameCtx(Context altNameCtx) {

   278         this.altNameCtx = altNameCtx;

   279     }

   280 

   281 

   282     /**

   283      * Use serialVersionUID from JNDI 1.1.1 for interoperability

   284      */

   285     private static final long serialVersionUID = 1219724816191576813L;

   286 }