View Javadoc
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.ldap;
27  
28  import javax.naming.ReferralException;
29  import javax.naming.Context;
30  import javax.naming.NamingException;
31  import java.util.Hashtable;
32  
33  /**
34   * This abstract class is used to represent an LDAP referral exception.
35   * It extends the base <tt>ReferralException</tt> by providing a
36   * <tt>getReferralContext()</tt> method that accepts request controls.
37   * LdapReferralException is an abstract class. Concrete implementations of it
38   * determine its synchronization and serialization properties.
39   *<p>
40   * A <tt>Control[]</tt> array passed as a parameter to
41   * the <tt>getReferralContext()</tt> method is owned by the caller.
42   * The service provider will not modify the array or keep a reference to it,
43   * although it may keep references to the individual <tt>Control</tt> objects
44   * in the array.
45   *
46   * @author Rosanna Lee
47   * @author Scott Seligman
48   * @author Vincent Ryan
49   * @since 1.3
50   */
51  
52  public abstract class LdapReferralException extends ReferralException {
53      /**
54       * Constructs a new instance of LdapReferralException using the
55       * explanation supplied. All other fields are set to null.
56       *
57       * @param   explanation     Additional detail about this exception. Can be null.
58       * @see java.lang.Throwable#getMessage
59       */
60      protected LdapReferralException(String explanation) {
61          super(explanation);
62      }
63  
64      /**
65        * Constructs a new instance of LdapReferralException.
66        * All fields are set to null.
67        */
68      protected LdapReferralException() {
69          super();
70      }
71  
72      /**
73       * Retrieves the context at which to continue the method using the
74       * context's environment and no controls.
75       * The referral context is created using the environment properties of
76       * the context that threw the <tt>ReferralException</tt> and no controls.
77       *<p>
78       * This method is equivalent to
79       *<blockquote><pre>
80       * getReferralContext(ctx.getEnvironment(), null);
81       *</pre></blockquote>
82       * where <tt>ctx</tt> is the context that threw the <tt>ReferralException.</tt>
83       *<p>
84       * It is overridden in this class for documentation purposes only.
85       * See <tt>ReferralException</tt> for how to use this method.
86       *
87       * @return The non-null context at which to continue the method.
88       * @exception NamingException If a naming exception was encountered.
89       * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
90       * to continue processing referrals.
91       */
92      public abstract Context getReferralContext() throws NamingException;
93  
94      /**
95       * Retrieves the context at which to continue the method using
96       * environment properties and no controls.
97       * The referral context is created using <tt>env</tt> as its environment
98       * properties and no controls.
99       *<p>
100      * This method is equivalent to
101      *<blockquote><pre>
102      * getReferralContext(env, null);
103      *</pre></blockquote>
104      *<p>
105      * It is overridden in this class for documentation purposes only.
106      * See <tt>ReferralException</tt> for how to use this method.
107      *
108      * @param env The possibly null environment to use when retrieving the
109      *          referral context. If null, no environment properties will be used.
110      *
111      * @return The non-null context at which to continue the method.
112      * @exception NamingException If a naming exception was encountered.
113      * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
114      * to continue processing referrals.
115      */
116     public abstract Context
117         getReferralContext(Hashtable<?,?> env)
118         throws NamingException;
119 
120     /**
121      * Retrieves the context at which to continue the method using
122      * request controls and environment properties.
123      * Regardless of whether a referral is encountered directly during a
124      * context operation, or indirectly, for example, during a search
125      * enumeration, the referral exception should provide a context
126      * at which to continue the operation.
127      * To continue the operation, the client program should re-invoke
128      * the method using the same arguments as the original invocation.
129      *<p>
130      * <tt>reqCtls</tt> is used when creating the connection to the referred
131      * server. These controls will be used as the connection request controls for
132      * the context and context instances
133      * derived from the context.
134      * <tt>reqCtls</tt> will also be the context's request controls for
135      * subsequent context operations. See the <tt>LdapContext</tt> class
136      * description for details.
137      *<p>
138      * This method should be used instead of the other two overloaded forms
139      * when the caller needs to supply request controls for creating
140      * the referral context. It might need to do this, for example, when
141      * it needs to supply special controls relating to authentication.
142      *<p>
143      * Service provider implementors should read the "Service Provider" section
144      * in the <tt>LdapContext</tt> class description for implementation details.
145      *
146      * @param reqCtls The possibly null request controls to use for the new context.
147      * If null or the empty array means use no request controls.
148      * @param env The possibly null environment properties to use when
149      * for the new context. If null, the context is initialized with no environment
150      * properties.
151      * @return The non-null context at which to continue the method.
152      * @exception NamingException If a naming exception was encountered.
153      * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
154      * to continue processing referrals.
155      */
156     public abstract Context
157         getReferralContext(Hashtable<?,?> env,
158                            Control[] reqCtls)
159         throws NamingException;
160 
161     private static final long serialVersionUID = -1668992791764950804L;
162 }