LdapReferralException


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