ReferralException


1   /*
2    * @(#)ReferralException.java   1.11 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;
9   
10  import java.util.Hashtable  ;
11  
12  /**
13   * This abstract class is used to represent a referral exception,
14   * which is generated in response to a <em>referral</em>
15   * such as that returned by LDAP v3 servers.
16   * <p>
17   * A service provider provides
18   * a subclass of <tt>ReferralException</tt> by providing implementations
19   * for <tt>getReferralInfo()</tt> and <tt>getReferralContext()</tt> (and appropriate
20   * constructors and/or corresponding "set" methods).
21   * <p>
22   * The following code sample shows how <tt>ReferralException</tt> can be used.
23   * <p><blockquote><pre>
24   *  while (true) {
25   *      try {
26   *      bindings = ctx.listBindings(name);
27   *      while (bindings.hasMore()) {
28   *          b = bindings.next();
29   *          ...
30   *      }
31   *      break;
32   *      } catch (ReferralException e) {
33   *      ctx = e.getReferralContext();
34   *      }
35   *  }
36   * </pre></blockquote></p>
37   *<p>
38   * <tt>ReferralException</tt> is an abstract class. Concrete implementations
39   * determine its synchronization and serialization properties.
40   *<p>
41   * An environment parameter passed to the <tt>getReferralContext()</tt>
42   * method is owned by the caller.
43   * The service provider will not modify the object or keep a reference to it,
44   * but may keep a reference to a clone of it.
45   * 
46   * @author Rosanna Lee
47   * @author Scott Seligman
48   * @version 1.11 04/07/16
49   *
50   * @since 1.3
51   *
52   */
53  
54  public abstract class ReferralException extends NamingException   {
55      /**
56       * Constructs a new instance of ReferralException using the
57       * explanation supplied. All other fields are set to null.
58       *
59       * @param   explanation Additional detail about this exception. Can be null.
60       * @see java.lang.Throwable#getMessage
61       */
62      protected ReferralException(String   explanation) {
63      super(explanation);
64      }
65  
66      /**
67        * Constructs a new instance of ReferralException.
68        * All fields are set to null.
69        */
70      protected ReferralException() {
71      super();
72      }
73  
74      /**
75       * Retrieves information (such as URLs) related to this referral.
76       * The program may examine or display this information
77       * to the user to determine whether to continue with the referral,
78       * or to determine additional information needs to be supplied in order
79       * to continue with the referral.
80       *
81       * @return Non-null referral information related to this referral.
82       */
83      public abstract Object   getReferralInfo();
84  
85      /**
86       * Retrieves the context at which to continue the method.
87       * Regardless of whether a referral is encountered directly during a 
88       * context operation, or indirectly, for example, during a search
89       * enumeration, the referral exception should provide a context
90       * at which to continue the operation. The referral context is
91       * created using the environment properties of the context
92       * that threw the ReferralException.
93       *
94       *<p>
95       * To continue the operation, the client program should re-invoke
96       * the method using the same arguments as the original invocation.
97       * 
98       * @return The non-null context at which to continue the method.
99       * @exception NamingException If a naming exception was encountered.
100      * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
101      * to continue processing referrals.
102      */
103     public abstract Context   getReferralContext() throws NamingException  ;
104 
105     /**
106      * Retrieves the context at which to continue the method using 
107      * environment properties.
108      * Regardless of whether a referral is encountered directly during a 
109      * context operation, or indirectly, for example, during a search
110      * enumeration, the referral exception should provide a context
111      * at which to continue the operation.
112      *<p>
113      * The referral context is created using <tt>env</tt> as its environment
114      * properties.
115      * This method should be used instead of the no-arg overloaded form
116      * when the caller needs to use different environment properties for
117      * the referral context. It might need to do this, for example, when
118      * it needs to supply different authentication information to the referred
119      * server in order to create the referral context.
120      *<p>
121      * To continue the operation, the client program should re-invoke
122      * the method using the same arguments as the original invocation.
123      * 
124      * @param env The possibly null environment to use when retrieving the 
125      *      referral context. If null, no environment properties will be used.
126      *
127      * @return The non-null context at which to continue the method.
128      * @exception NamingException If a naming exception was encountered.
129      * Call either <tt>retryReferral()</tt> or <tt>skipReferral()</tt>
130      * to continue processing referrals.
131      */
132     public abstract Context  
133     getReferralContext(Hashtable  <?,?> env)
134     throws NamingException  ;
135 
136     /**
137      * Discards the referral about to be processed.
138      * A call to this method should be followed by a call to
139      * <code>getReferralContext</code> to allow the processing of
140      * other referrals to continue.
141      * The following code fragment shows a typical usage pattern.
142      * <p><blockquote><pre>
143      *  } catch (ReferralException e) {
144      *      if (!shallIFollow(e.getReferralInfo())) {
145      *      if (!e.skipReferral()) {
146      *          return;
147      *      }
148      *      }
149      *      ctx = e.getReferralContext();
150      *  }
151      * </pre></blockquote>
152      *
153      * @return true If more referral processing is pending; false otherwise.
154      */
155     public abstract boolean skipReferral();
156 
157     /**
158      * Retries the referral currently being processed.
159      * A call to this method should be followed by a call to
160      * <code>getReferralContext</code> to allow the current
161      * referral to be retried.
162      * The following code fragment shows a typical usage pattern.
163      * <p><blockquote><pre>
164      *  } catch (ReferralException e) {
165      *      while (true) {
166      *      try {
167      *          ctx = e.getReferralContext(env);
168      *          break;
169      *      } catch (NamingException ne) {
170      *          if (! shallIRetry()) {
171      *          return;
172      *          }
173      *          // modify environment properties (env), if necessary
174      *          e.retryReferral();
175      *      }
176      *      }
177      *  }
178      * </pre></blockquote>
179      *
180      */
181     public abstract void retryReferral();
182 
183     /**
184      * Use serialVersionUID from JNDI 1.1.1 for interoperability
185      */
186     private static final long serialVersionUID = -2881363844695698876L;
187 }
188
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags