KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > ldap > InitialLdapContext


1 /*
2  * @(#)InitialLdapContext.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.*;
11 import javax.naming.directory.*;
12
13 import java.util.Hashtable JavaDoc;
14
15 /**
16   * This class is the starting context for performing
17   * LDAPv3-style extended operations and controls.
18   *<p>
19   * See <tt>javax.naming.InitialContext</tt> and
20   * <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
21   * and the policy for how an initial context is created.
22   *
23   * <h4>Request Controls</h4>
24   * When you create an initial context (<tt>InitialLdapContext</tt>),
25   * you can specify a list of request controls.
26   * These controls will be used as the request controls for any
27   * implicit LDAP "bind" operation performed by the context or contexts
28   * derived from the context. These are called <em>connection request controls</em>.
29   * Use <tt>getConnectControls()</tt> to get a context's connection request
30   * controls.
31   *<p>
32   * The request controls supplied to the initial context constructor
33   * are <em>not</em> used as the context request controls
34   * for subsequent context operations such as searches and lookups.
35   * Context request controls are set and updated by using
36   * <tt>setRequestControls()</tt>.
37   *<p>
38   * As shown, there can be two different sets of request controls
39   * associated with a context: connection request controls and context
40   * request controls.
41   * This is required for those applications needing to send critical
42   * controls that might not be applicable to both the context operation and
43   * any implicit LDAP "bind" operation.
44   * A typical user program would do the following:
45   *<blockquote><pre>
46   * InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
47   * lctx.setRequestControls(critModCtls);
48   * lctx.modifyAttributes(name, mods);
49   * Controls[] respCtls = lctx.getResponseControls();
50   *</pre></blockquote>
51   * It specifies first the critical controls for creating the initial context
52   * (<tt>critConnCtls</tt>), and then sets the context's request controls
53   * (<tt>critModCtls</tt>) for the context operation. If for some reason
54   * <tt>lctx</tt> needs to reconnect to the server, it will use
55   * <tt>critConnCtls</tt>. See the <tt>LdapContext</tt> interface for
56   * more discussion about request controls.
57   *<p>
58   * Service provider implementors should read the "Service Provider" section
59   * in the <tt>LdapContext</tt> class description for implementation details.
60   *
61   * @author Rosanna Lee
62   * @author Scott Seligman
63   * @author Vincent Ryan
64   * @version 1.12 04/07/16
65   *
66   * @see LdapContext
67   * @see javax.naming.InitialContext
68   * @see javax.naming.directory.InitialDirContext
69   * @see javax.naming.spi.NamingManager#setInitialContextFactoryBuilder
70   * @since 1.3
71   */
72
73 public class InitialLdapContext extends InitialDirContext implements LdapContext JavaDoc {
74     private static final String JavaDoc
75         BIND_CONTROLS_PROPERTY = "java.naming.ldap.control.connect";
76
77     /**
78      * Constructs an initial context using no environment properties or
79      * connection request controls.
80      * Equivalent to <tt>new InitialLdapContext(null, null)</tt>.
81      *
82      * @throws NamingException if a naming exception is encountered
83      */
84     public InitialLdapContext() throws NamingException {
85     super(null);
86     }
87
88     /**
89      * Constructs an initial context
90      * using environment properties and connection request controls.
91      * See <tt>javax.naming.InitialContext</tt> for a discussion of
92      * environment properties.
93      *
94      * <p> This constructor will not modify its parameters or
95      * save references to them, but may save a clone or copy.
96      *
97      * <p> <tt>connCtls</tt> is used as the underlying context instance's
98      * connection request controls. See the class description
99      * for details.
100      *
101      * @param environment
102      * environment used to create the initial DirContext.
103      * Null indicates an empty environment.
104      * @param connCtls
105      * connection request controls for the initial context.
106      * If null, no connection request controls are used.
107      *
108      * @throws NamingException if a naming exception is encountered
109      *
110      * @see #reconnect
111      * @see LdapContext#reconnect
112      */
113     public InitialLdapContext(Hashtable JavaDoc<?,?> environment,
114                   Control JavaDoc[] connCtls)
115         throws NamingException {
116     super(true); // don't initialize yet
117
118     // Clone environment since caller owns it.
119 Hashtable JavaDoc env = (environment == null)
120         ? new Hashtable JavaDoc(11)
121         : (Hashtable JavaDoc)environment.clone();
122
123     // Put connect controls into environment. Copy them first since
124 // caller owns the array.
125 if (connCtls != null) {
126         Control JavaDoc[] copy = new Control JavaDoc[connCtls.length];
127         System.arraycopy(connCtls, 0, copy, 0, connCtls.length);
128         env.put(BIND_CONTROLS_PROPERTY, copy);
129     }
130     // set version to LDAPv3
131 env.put("java.naming.ldap.version", "3");
132
133     // Initialize with updated environment
134 init(env);
135     }
136
137     /**
138      * Retrieves the initial LDAP context.
139      *
140      * @return The non-null cached initial context.
141      * @exception NotContextException If the initial context is not an
142      * instance of <tt>LdapContext</tt>.
143      * @exception NamingException If a naming exception was encountered.
144      */
145     private LdapContext JavaDoc getDefaultLdapInitCtx() throws NamingException{
146     Context answer = getDefaultInitCtx();
147
148     if (!(answer instanceof LdapContext JavaDoc)) {
149         if (answer == null) {
150         throw new NoInitialContextException();
151         } else {
152         throw new NotContextException(
153             "Not an instance of LdapContext");
154         }
155     }
156     return (LdapContext JavaDoc)answer;
157     }
158
159 // LdapContext methods
160 // Most Javadoc is deferred to the LdapContext interface.
161
162     public ExtendedResponse JavaDoc extendedOperation(ExtendedRequest JavaDoc request)
163         throws NamingException {
164     return getDefaultLdapInitCtx().extendedOperation(request);
165     }
166
167     public LdapContext JavaDoc newInstance(Control JavaDoc[] reqCtls)
168     throws NamingException {
169         return getDefaultLdapInitCtx().newInstance(reqCtls);
170     }
171
172     public void reconnect(Control JavaDoc[] connCtls) throws NamingException {
173     getDefaultLdapInitCtx().reconnect(connCtls);
174     }
175
176     public Control JavaDoc[] getConnectControls() throws NamingException {
177     return getDefaultLdapInitCtx().getConnectControls();
178     }
179
180     public void setRequestControls(Control JavaDoc[] requestControls)
181     throws NamingException {
182         getDefaultLdapInitCtx().setRequestControls(requestControls);
183     }
184
185     public Control JavaDoc[] getRequestControls() throws NamingException {
186     return getDefaultLdapInitCtx().getRequestControls();
187     }
188
189     public Control JavaDoc[] getResponseControls() throws NamingException {
190     return getDefaultLdapInitCtx().getResponseControls();
191     }
192 }
193
Popular Tags