public final class

LdapCtx

extends ComponentDirContext
implements EventDirContext LdapContext
java.lang.Object
   ↳ com.sun.jndi.toolkit.ctx.PartialCompositeContext
     ↳ com.sun.jndi.toolkit.ctx.ComponentContext
       ↳ com.sun.jndi.toolkit.ctx.AtomicContext
         ↳ com.sun.jndi.toolkit.ctx.PartialCompositeDirContext
           ↳ com.sun.jndi.toolkit.ctx.ComponentDirContext
             ↳ com.sun.jndi.ldap.LdapCtx

Class Overview

The LDAP context implementation. Implementation is not thread-safe. Caller must sync as per JNDI spec. Members that are used directly or indirectly by internal worker threads (Connection, EventQueue, NamingEventNotifier) must be thread-safe. Connection - calls LdapClient.processUnsolicited(), which in turn calls LdapCtx.convertControls() and LdapCtx.fireUnsolicited(). convertControls() - no sync; reads envprops and 'this' fireUnsolicited() - sync on eventSupport for all references to 'unsolicited' (even those in other methods); don't sync on LdapCtx in case caller is already sync'ing on it - this would prevent Unsol events from firing and the Connection thread to block (thus preventing any other data from being read from the connection) References to 'eventSupport' need not be sync'ed because these methods can only be called after eventSupport has been set first (via addNamingListener()). EventQueue - no direct or indirect calls to LdapCtx NamingEventNotifier - calls newInstance() to get instance for run() to use; no sync needed for methods invoked on new instance; LdapAttribute links to LdapCtx in order to process getAttributeDefinition() and getAttributeSyntaxDefinition() calls. It invokes LdapCtx.getSchema(), which uses schemaTrees (a Hashtable - already sync). Potential conflict of duplicating construction of tree for same subschemasubentry but no inconsistency problems. NamingEnumerations link to LdapCtx for the following: 1. increment/decrement enum count so that ctx doesn't close the underlying connection 2. LdapClient handle to get next batch of results 3. Sets LdapCtx's response controls 4. Process return code 5. For narrowing response controls (using ctx's factories) Since processing of NamingEnumeration by client is treated the same as method invocation on LdapCtx, caller is responsible for locking.

Summary

Constants
String DEFAULT_HOST
int DEFAULT_PORT
int DEFAULT_SSL_PORT
[Expand]
Inherited Constants
From class com.sun.jndi.toolkit.ctx.ComponentContext
From class com.sun.jndi.toolkit.ctx.PartialCompositeContext
From interface javax.naming.Context
From interface javax.naming.directory.DirContext
From interface javax.naming.event.EventContext
From interface javax.naming.ldap.LdapContext
[Expand]
Inherited Fields
From class com.sun.jndi.toolkit.ctx.PartialCompositeContext
Public Constructors
LdapCtx(String dn, String host, int port_number, Hashtable props, boolean useSsl)
Public Methods
void addNamingListener(String nm, String filter, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified.
void addNamingListener(Name nm, String filter, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.
void addNamingListener(String nm, String filterExpr, Object[] filterArgs, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified.
void addNamingListener(Name nm, int scope, NamingListener l)
Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes.
void addNamingListener(String nm, int scope, NamingListener l)
Adds a listener for receiving naming events fired when the object named by the string target name and scope changes.
void addNamingListener(Name nm, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
Object addToEnvironment(String propName, Object propVal)
Adds a new environment property to the environment of this context.
synchronized void close()
Closes this context.
Name composeName(Name name, Name prefix)
This default implementation simply concatenates the two names.
ExtendedResponse extendedOperation(ExtendedRequest request)
Performs an extended operation.
Control[] getConnectControls()
Retrieves the connection request controls in effect for this context.
Hashtable getEnvironment()
Retrieves the environment in effect for this context.
String getNameInNamespace()
Retrieves the full name of this context within its own namespace.
Control[] getRequestControls()
Retrieves the request controls in effect for this context.
Control[] getResponseControls()
Retrieves the response controls produced as a result of the last method invoked on this context.
static NamingException mapErrorCode(int errorCode, String errorMessage)
Maps an LDAP error code to an appropriate NamingException.
LdapContext newInstance(Control[] reqCtls)
Creates a new instance of this context initialized using request controls.
void reconnect(Control[] connCtls)
Reconnects to the LDAP server using the supplied controls and this context's environment.
Object removeFromEnvironment(String propName)
Removes an environment property from the environment of this context.
void removeNamingListener(NamingListener l)
Removes a listener from receiving naming events fired by this EventContext.
void setRequestControls(Control[] reqCtls)
Sets the request controls for methods subsequently invoked on this context.
boolean targetMustExist()
Determines whether a listener can register interest in a target that does not exist.
Protected Methods
void c_bind(Name name, Object obj, Continuation cont)
void c_bind(Name name, Object obj, Attributes attrs, Continuation cont)
DirContext c_createSubcontext(Name name, Attributes attrs, Continuation cont)
Context c_createSubcontext(Name name, Continuation cont)
void c_destroySubcontext(Name name, Continuation cont)
Attributes c_getAttributes(Name name, String[] attrIds, Continuation cont)
NameParser c_getNameParser(Name name, Continuation cont)
DirContext c_getSchema(Name name, Continuation cont)
DirContext c_getSchemaClassDefinition(Name name, Continuation cont)
NamingEnumeration c_list(Name name, Continuation cont)
NamingEnumeration c_listBindings(Name name, Continuation cont)
Object c_lookup(Name name, Continuation cont)
Object c_lookupLink(Name name, Continuation cont)
void c_modifyAttributes(Name name, int mod_op, Attributes attrs, Continuation cont)
void c_modifyAttributes(Name name, ModificationItem[] mods, Continuation cont)
void c_rebind(Name name, Object obj, Attributes attrs, Continuation cont)
void c_rebind(Name name, Object obj, Continuation cont)
void c_rename(Name oldName, Name newName, Continuation cont)
NamingEnumeration c_search(Name name, Attributes matchingAttributes, String[] attributesToReturn, Continuation cont)
NamingEnumeration c_search(Name name, Attributes matchingAttributes, Continuation cont)
NamingEnumeration c_search(Name name, String filter, SearchControls cons, Continuation cont)
NamingEnumeration c_search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons, Continuation cont)
void c_unbind(Name name, Continuation cont)
void finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
Hashtable p_getEnvironment()
Override with noncloning version.
void processReturnCode(LdapResult res, Name resolvedName, Object resolvedObj, Name remainName, Hashtable envprops, String fullDN)
void processReturnCode(LdapResult answer)
[Expand]
Inherited Methods
From class com.sun.jndi.toolkit.ctx.ComponentDirContext
From class com.sun.jndi.toolkit.ctx.PartialCompositeDirContext
From class com.sun.jndi.toolkit.ctx.AtomicContext
From class com.sun.jndi.toolkit.ctx.ComponentContext
From class com.sun.jndi.toolkit.ctx.PartialCompositeContext
From class java.lang.Object
From interface javax.naming.Context
From interface javax.naming.directory.DirContext
From interface javax.naming.event.EventContext
From interface javax.naming.event.EventDirContext
From interface javax.naming.ldap.LdapContext
From interface javax.naming.spi.Resolver

Constants

public static final String DEFAULT_HOST

Constant Value: "localhost"

public static final int DEFAULT_PORT

Constant Value: 389 (0x00000185)

public static final int DEFAULT_SSL_PORT

Constant Value: 636 (0x0000027c)

Public Constructors

public LdapCtx (String dn, String host, int port_number, Hashtable props, boolean useSsl)

Public Methods

public void addNamingListener (String nm, String filter, SearchControls ctls, NamingListener l)

Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified. See the overload that accepts a Name for details of how this method behaves.

Parameters
nm The nonnull string name of the object resolved relative to this context.
filter The nonnull string filter (see RFC2254).
ctls The possibly null search controls. If null, the default search controls is used.
l The nonnull listener.

public void addNamingListener (Name nm, String filter, SearchControls ctls, NamingListener l)

Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.

The scope, returningObj flag, and returningAttributes flag from the search controls ctls are used to control the selection of objects that the listener is interested in, and determines what information is returned in the eventual NamingEvent object. Note that the requested information to be returned might not be present in the NamingEvent object if they are unavailable or could not be obtained by the service provider or service.

Parameters
nm The nonnull name of the object resolved relative to this context.
filter The nonnull string filter (see RFC2254).
ctls The possibly null search controls. If null, the default search controls are used.
l The nonnull listener.

public void addNamingListener (String nm, String filterExpr, Object[] filterArgs, SearchControls ctls, NamingListener l)

Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified. See the overload that accepts a Name for details of how this method behaves.

Parameters
nm The nonnull string name of the object resolved relative to this context.
filterExpr The nonnull string filter (see RFC2254).
filterArgs The possibly null array of arguments for the filter.
ctls The possibly null search controls. If null, the default search controls is used.
l The nonnull listener.

public void addNamingListener (Name nm, int scope, NamingListener l)

Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes. The event source of those events is this context. See the class description for a discussion on event source and target. See the descriptions of the constants OBJECT_SCOPE, ONELEVEL_SCOPE, and SUBTREE_SCOPE to see how scope affects the registration.

target needs to name a context only when scope is ONELEVEL_SCOPE. target may name a non-context if scope is either OBJECT_SCOPE or SUBTREE_SCOPE. Using SUBTREE_SCOPE for a non-context might be useful, for example, if the caller does not know in advance whether target is a context and just wants to register interest in the (possibly degenerate subtree) rooted at target.

When the listener is notified of an event, the listener may in invoked in a thread other than the one in which addNamingListener() is executed. Care must be taken when multiple threads are accessing the same EventContext concurrently. See the package description for more information on threading issues.

Parameters
nm A nonnull name to be resolved relative to this context.
scope One of OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE.
l The nonnull listener.

public void addNamingListener (String nm, int scope, NamingListener l)

Adds a listener for receiving naming events fired when the object named by the string target name and scope changes. See the overload that accepts a Name for details.

Parameters
nm The nonnull string name of the object resolved relative to this context.
scope One of OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE.
l The nonnull listener.

public void addNamingListener (Name nm, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l)

Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified. The scope, returningObj flag, and returningAttributes flag from the search controls ctls are used to control the selection of objects that the listener is interested in, and determines what information is returned in the eventual NamingEvent object. Note that the requested information to be returned might not be present in the NamingEvent object if they are unavailable or could not be obtained by the service provider or service.

Parameters
nm The nonnull name of the object resolved relative to this context.
filter The nonnull string filter (see RFC2254).
filterArgs The possibly null array of arguments for the filter.
ctls The possibly null search controls. If null, the default search controls are used.
l The nonnull listener.

public Object addToEnvironment (String propName, Object propVal)

Adds a new environment property to the environment of this context. If the property already exists, its value is overwritten. See class description for more details on environment properties.

Parameters
propName the name of the environment property to add; may not be null
propVal the value of the property to add; may not be null
Returns
  • the previous value of the property, or null if the property was not in the environment before

public synchronized void close ()

Closes this context. This method releases this context's resources immediately, instead of waiting for them to be released automatically by the garbage collector.

This method is idempotent: invoking it on a context that has already been closed has no effect. Invoking any other method on a closed context is not allowed, and results in undefined behaviour.

public Name composeName (Name name, Name prefix)

This default implementation simply concatenates the two names. There's one twist when the "java.naming.provider.compose.elideEmpty" environment setting is set to "true": if each name contains a nonempty component, and if 'prefix' ends with an empty component or 'name' starts with one, then one empty component is dropped. For example:

                            elideEmpty=false     elideEmpty=true
 {"a"} + {"b"}          =>  {"a", "b"}           {"a", "b"}
 {"a"} + {""}           =>  {"a", ""}            {"a", ""}
 {"a"} + {"", "b"}      =>  {"a", "", "b"}       {"a", "b"}
 {"a", ""} + {"b", ""}  =>  {"a", "", "b", ""}   {"a", "b", ""}
 {"a", ""} + {"", "b"}  =>  {"a", "", "", "b"}   {"a", "", "b"}
 

Parameters
name a name relative to this context
prefix the name of this context relative to one of its ancestors
Returns
  • the composition of prefix and name

public ExtendedResponse extendedOperation (ExtendedRequest request)

Performs an extended operation. This method is used to support LDAPv3 extended operations.

Parameters
request The non-null request to be performed.
Returns
  • The possibly null response of the operation. null means the operation did not generate any response.

public Control[] getConnectControls ()

Retrieves the connection request controls in effect for this context. The controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns
  • A possibly-null array of controls. null means no connect controls have been set for this context.

public Hashtable getEnvironment ()

Retrieves the environment in effect for this context. See class description for more details on environment properties.

The caller should not make any changes to the object returned: their effect on the context is undefined. The environment of this context may be changed using addToEnvironment() and removeFromEnvironment().

Returns
  • the environment of this context; never null

public String getNameInNamespace ()

Retrieves the full name of this context within its own namespace.

Many naming services have a notion of a "full name" for objects in their respective namespaces. For example, an LDAP entry has a distinguished name, and a DNS record has a fully qualified name. This method allows the client application to retrieve this name. The string returned by this method is not a JNDI composite name and should not be passed directly to context methods. In naming systems for which the notion of full name does not make sense, OperationNotSupportedException is thrown.

Returns
  • this context's name in its own namespace; never null

public Control[] getRequestControls ()

Retrieves the request controls in effect for this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns
  • A possibly-null array of controls. null means no request controls have been set for this context.

public Control[] getResponseControls ()

Retrieves the response controls produced as a result of the last method invoked on this context. The response controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

These response controls might have been generated by a successful or failed operation.

When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.

Returns
  • A possibly null array of controls. If null, the previous method invoked on this context did not produce any controls.

public static NamingException mapErrorCode (int errorCode, String errorMessage)

Maps an LDAP error code to an appropriate NamingException. %%% public; used by controls

Parameters
errorCode numeric LDAP error code
errorMessage textual description of the LDAP error. May be null.
Returns
  • A NamingException or null if the error code indicates success.

public LdapContext newInstance (Control[] reqCtls)

Creates a new instance of this context initialized using request controls. This method is a convenience method for creating a new instance of this context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.

Parameters
reqCtls The possibly null request controls to use for the new context. If null, the context is initialized with no request controls.
Returns
  • A non-null LdapContext instance.

public void reconnect (Control[] connCtls)

Reconnects to the LDAP server using the supplied controls and this context's environment.

This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.

This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().

Service provider implementors should read the "Service Provider" section in the class description for implementation details.

Parameters
connCtls The possibly null controls to use. If null, no controls are used.

public Object removeFromEnvironment (String propName)

Removes an environment property from the environment of this context. See class description for more details on environment properties.

Parameters
propName the name of the environment property to remove; may not be null
Returns
  • the previous value of the property, or null if the property was not in the environment

public void removeNamingListener (NamingListener l)

Removes a listener from receiving naming events fired by this EventContext. The listener may have registered more than once with this EventContext, perhaps with different target/scope arguments. After this method is invoked, the listener will no longer receive events with this EventContext instance as the event source (except for those events already in the process of being dispatched). If the listener was not, or is no longer, registered with this EventContext instance, this method does not do anything.

Parameters
l The nonnull listener.

public void setRequestControls (Control[] reqCtls)

Sets the request controls for methods subsequently invoked on this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.

Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().

Parameters
reqCtls The possibly null controls to use. If null, no controls are used.

public boolean targetMustExist ()

Determines whether a listener can register interest in a target that does not exist.

Returns
  • true if the target must exist; false if the target need not exist.

Protected Methods

protected void c_bind (Name name, Object obj, Continuation cont)

protected void c_bind (Name name, Object obj, Attributes attrs, Continuation cont)

protected DirContext c_createSubcontext (Name name, Attributes attrs, Continuation cont)

protected Context c_createSubcontext (Name name, Continuation cont)

protected void c_destroySubcontext (Name name, Continuation cont)

protected Attributes c_getAttributes (Name name, String[] attrIds, Continuation cont)

protected NameParser c_getNameParser (Name name, Continuation cont)

protected DirContext c_getSchema (Name name, Continuation cont)

protected DirContext c_getSchemaClassDefinition (Name name, Continuation cont)

protected NamingEnumeration c_list (Name name, Continuation cont)

protected NamingEnumeration c_listBindings (Name name, Continuation cont)

protected Object c_lookup (Name name, Continuation cont)

protected Object c_lookupLink (Name name, Continuation cont)

protected void c_modifyAttributes (Name name, int mod_op, Attributes attrs, Continuation cont)

protected void c_modifyAttributes (Name name, ModificationItem[] mods, Continuation cont)

protected void c_rebind (Name name, Object obj, Attributes attrs, Continuation cont)

protected void c_rebind (Name name, Object obj, Continuation cont)

protected void c_rename (Name oldName, Name newName, Continuation cont)

protected NamingEnumeration c_search (Name name, Attributes matchingAttributes, String[] attributesToReturn, Continuation cont)

protected NamingEnumeration c_search (Name name, Attributes matchingAttributes, Continuation cont)

protected NamingEnumeration c_search (Name name, String filter, SearchControls cons, Continuation cont)

protected NamingEnumeration c_search (Name name, String filterExpr, Object[] filterArgs, SearchControls cons, Continuation cont)

protected void c_unbind (Name name, Continuation cont)

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the JavaTM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

protected Hashtable p_getEnvironment ()

Override with noncloning version.

Returns
  • The possibly null environment of the context.

protected void processReturnCode (LdapResult res, Name resolvedName, Object resolvedObj, Name remainName, Hashtable envprops, String fullDN)

protected void processReturnCode (LdapResult answer)