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
26package javax.naming.ldap;
27
28import javax.naming.ReferralException;
29import javax.naming.Context;
30import javax.naming.NamingException;
31import java.util.Hashtable;
32
33/**
34 * This abstract class is used to represent an LDAP referral exception.
35 * It extends the base {@code ReferralException} by providing a
36 * {@code getReferralContext()} 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 {@code Control[]} array passed as a parameter to
41 * the {@code getReferralContext()} 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 {@code Control} objects
44 * in the array.
45 *
46 * @author Rosanna Lee
47 * @author Scott Seligman
48 * @author Vincent Ryan
49 * @since 1.3
50 */
51
52public 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 {@code ReferralException} and no controls.
77     *<p>
78     * This method is equivalent to
79     *<blockquote><pre>
80     * getReferralContext(ctx.getEnvironment(), null);
81     *</pre></blockquote>
82     * where {@code ctx} is the context that threw the {@code ReferralException.}
83     *<p>
84     * It is overridden in this class for documentation purposes only.
85     * See {@code ReferralException} 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 {@code retryReferral()} or {@code skipReferral()}
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 {@code env} 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 {@code ReferralException} 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 {@code retryReferral()} or {@code skipReferral()}
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     * {@code reqCtls} 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     * {@code reqCtls} will also be the context's request controls for
135     * subsequent context operations. See the {@code LdapContext} 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 {@code LdapContext} 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 {@code retryReferral()} or {@code skipReferral()}
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}
163