org.forgerock.openig.ldap

Class LdapConnection

java.lang.Object

org.forgerock.openig.ldap.LdapConnection

All Implemented Interfaces:

Closeable, AutoCloseable

public final class LdapConnection
extends Object
implements Closeable

Provides an adapted view of an OpenDJ LDAP connection exposing only the synchronous methods and protecting against future evolution of the Connection interface (e.g. migration to Promises).

Method Summary

Modifier and Type	Method and Description
Result	add(AddRequest request) Adds an entry to the Directory Server using the provided add request.
Result	add(Entry entry) Adds the provided entry to the Directory Server.
Result	add(String... ldifLines) Adds an entry to the Directory Server using the provided lines of LDIF.
BindResult	bind(BindRequest request) Authenticates to the Directory Server using the provided bind request.
BindResult	bind(String name, char[] password) Authenticates to the Directory Server using simple authentication and the provided user name and password.
void	close() Releases any resources associated with this connection.
CompareResult	compare(CompareRequest request) Compares an entry in the Directory Server using the provided compare request.
CompareResult	compare(String name, String attributeDescription, String assertionValue) Compares the named entry in the Directory Server against the provided attribute value assertion.
Result	delete(DeleteRequest request) Deletes an entry from the Directory Server using the provided delete request.
Result	delete(String name) Deletes the named entry from the Directory Server.
Result	deleteSubtree(String name) Deletes the named entry and all of its subordinates from the Directory Server.
Result	modify(ModifyRequest request) Modifies an entry in the Directory Server using the provided modify request.
Result	modify(String... ldifLines) Modifies an entry in the Directory Server using the provided lines of LDIF.
Result	modifyDN(ModifyDnRequest request) Renames an entry in the Directory Server using the provided modify DN request.
Result	modifyDN(String name, String newRDN) Renames the named entry in the Directory Server using the provided new RDN.
SearchResultEntry	readEntry(Dn name, String... attributeDescriptions) Reads the named entry from the Directory Server.
SearchResultEntry	readEntry(String name, String... attributeDescriptions) Reads the named entry from the Directory Server.
ConnectionEntryReader	search(SearchRequest request) Searches the Directory Server using the provided search parameters.
Result	search(SearchRequest request, Collection<? super SearchResultEntry> entries) Searches the Directory Server using the provided search request.
Result	search(SearchRequest request, Collection<? super SearchResultEntry> entries, Collection<? super SearchResultReference> references) Searches the Directory Server using the provided search request.
ConnectionEntryReader	search(String baseObject, SearchScope scope, String filter, String... attributeDescriptions) Searches the Directory Server using the provided search parameters.
SearchResultEntry	searchSingleEntry(SearchRequest request) Searches the Directory Server for a single entry using the provided search request.
SearchResultEntry	searchSingleEntry(String baseObject, SearchScope scope, String filter, String... attributeDescriptions) Searches the Directory Server for a single entry using the provided search parameters.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

add

public Result add(AddRequest request)
           throws LdapException

Adds an entry to the Directory Server using the provided add request.

Parameters:

request - The add request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

add

public Result add(Entry entry)
           throws LdapException

Adds the provided entry to the Directory Server.

This method is equivalent to the following code:

 
 AddRequest request = newAddRequest(entry);
 connection.add(request);
 
 

Parameters:

entry - The entry to be added.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If entry was null .

add

public Result add(String... ldifLines)
           throws LdapException

Adds an entry to the Directory Server using the provided lines of LDIF.

This method is equivalent to the following code:

 
 AddRequest request = newAddRequest(ldifLines);
 connection.add(request);
 
 

Parameters:

ldifLines - Lines of LDIF containing the an LDIF add change record or an LDIF entry record.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

org.forgerock.i18n.LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If ldifLines was null .

bind

public BindResult bind(BindRequest request)
                throws LdapException

Authenticates to the Directory Server using the provided bind request.

Parameters:

request - The bind request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

bind

public BindResult bind(String name,
                       char[] password)
                throws LdapException

Authenticates to the Directory Server using simple authentication and the provided user name and password.

This method is equivalent to the following code:

 
 BindRequest request = newSimpleBindRequest(name, password);
 connection.bind(request);
 
 

Parameters:

name - The distinguished name of the Directory object that the client wishes to bind as, which may be empty.

password - The password of the Directory object that the client wishes to bind as, which may be empty.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name or password was null.

close

public void close()

Releases any resources associated with this connection. For physical connections to a Directory Server this will mean that an unbind request is sent and the underlying socket is closed.

Other connection implementations may behave differently, and may choose not to send an unbind request if its use is inappropriate (for example a pooled connection will be released and returned to its connection pool without ever issuing an unbind request).

This method is equivalent to the following code:

 
 UnbindRequest request = new UnbindRequest();
 connection.close(request);
 
 

Calling close on a connection that is already closed has no effect.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

See Also:

Connections.uncloseable(Connection)

compare

public CompareResult compare(CompareRequest request)
                      throws LdapException

Compares an entry in the Directory Server using the provided compare request.

Parameters:

request - The compare request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

compare

public CompareResult compare(String name,
                             String attributeDescription,
                             String assertionValue)
                      throws LdapException

Compares the named entry in the Directory Server against the provided attribute value assertion.

This method is equivalent to the following code:

 
 CompareRequest request = newCompareRequest(name, attributeDescription, assertionValue);
 connection.compare(request);
 
 

Parameters:

name - The distinguished name of the entry to be compared.

attributeDescription - The name of the attribute to be compared.

assertionValue - The assertion value to be compared.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If name or AttributeDescription could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name, attributeDescription, or assertionValue was null.

delete

public Result delete(DeleteRequest request)
              throws LdapException

Deletes an entry from the Directory Server using the provided delete request.

Parameters:

request - The delete request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

delete

public Result delete(String name)
              throws LdapException

Deletes the named entry from the Directory Server.

This method is equivalent to the following code:

 
 DeleteRequest request = newDeleteRequest(name);
 connection.delete(request);
 
 

Parameters:

name - The distinguished name of the entry to be deleted.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name was null.

deleteSubtree

public Result deleteSubtree(String name)
                     throws LdapException

Deletes the named entry and all of its subordinates from the Directory Server.

This method is equivalent to the following code:

 
 DeleteRequest request = newDeleteRequest(name).addControl(SubtreeDeleteRequestControl.newControl(true)));
 connection.delete(request);
 
 

Parameters:

name - The distinguished name of the subtree base entry to be deleted.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name was null.

modify

public Result modify(ModifyRequest request)
              throws LdapException

Modifies an entry in the Directory Server using the provided modify request.

Parameters:

request - The modify request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modify

public Result modify(String... ldifLines)
              throws LdapException

Modifies an entry in the Directory Server using the provided lines of LDIF.

This method is equivalent to the following code:

 
 ModifyRequest request = newModifyRequest(ldifLines);
 connection.modify(request);
 
 

Parameters:

ldifLines - Lines of LDIF containing the a single LDIF modify change record.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify operations.

org.forgerock.i18n.LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If ldifLines was null .

modifyDN

public Result modifyDN(ModifyDnRequest request)
                throws LdapException

Renames an entry in the Directory Server using the provided modify DN request.

Parameters:

request - The modify DN request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modifyDN

public Result modifyDN(String name,
                       String newRDN)
                throws LdapException

Renames the named entry in the Directory Server using the provided new RDN.

This method is equivalent to the following code:

 
 ModifyDNRequest request = newModifyDNRequest(name, newRDN);
 connection.modifyDN(request);
 
 

Parameters:

name - The distinguished name of the entry to be renamed.

newRDN - The new RDN of the entry.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If name or newRDN could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name or newRDN was null.

readEntry

public SearchResultEntry readEntry(Dn name,
                                   String... attributeDescriptions)
                            throws LdapException

Reads the named entry from the Directory Server.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null.

This method is equivalent to the following code:

 
 SearchRequest request =
         new SearchRequest(name, SearchScope.BASE_OBJECT, "(objectClass=*)", attributeDescriptions);
 connection.searchSingleEntry(request);
 
 

Parameters:

name - The distinguished name of the entry to be read.

attributeDescriptions - The names of the attributes to be included with the entry, which may be null or empty indicating that all user attributes should be returned.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the name was null.

readEntry

public SearchResultEntry readEntry(String name,
                                   String... attributeDescriptions)
                            throws LdapException

Reads the named entry from the Directory Server.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null.

This method is equivalent to the following code:

 
 SearchRequest request =
         new SearchRequest(name, SearchScope.BASE_OBJECT, "(objectClass=*)", attributeDescriptions);
 connection.searchSingleEntry(request);
 
 

Parameters:

name - The distinguished name of the entry to be read.

attributeDescriptions - The names of the attributes to be included with the entry.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If baseObject could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the name was null.

search

public ConnectionEntryReader search(SearchRequest request)

Searches the Directory Server using the provided search parameters. Any matching entries returned by the search will be exposed through the returned ConnectionEntryReader.

Unless otherwise specified, calling this method is equivalent to:

 
 ConnectionEntryReader reader = new ConnectionEntryReader(this, request);
 
 

Parameters:

request - The search request.

Returns:

The result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

public Result search(SearchRequest request,
                     Collection<? super SearchResultEntry> entries)
              throws LdapException

Searches the Directory Server using the provided search request. Any matching entries returned by the search will be added to entries, even if the final search result indicates that the search failed. Search result references will be discarded.

Warning: Usage of this method is discouraged if the search request is expected to yield a large number of search results since the entire set of results will be stored in memory, potentially causing an OutOfMemoryError.

This method is equivalent to the following code:

 
 connection.search(request, entries, null);
 
 

Parameters:

request - The search request.

entries - The collection to which matching entries should be added.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

public Result search(SearchRequest request,
                     Collection<? super SearchResultEntry> entries,
                     Collection<? super SearchResultReference> references)
              throws LdapException

Searches the Directory Server using the provided search request. Any matching entries returned by the search will be added to entries, even if the final search result indicates that the search failed. Similarly, search result references returned by the search will be added to references.

Warning: Usage of this method is discouraged if the search request is expected to yield a large number of search results since the entire set of results will be stored in memory, potentially causing an OutOfMemoryError.

Parameters:

request - The search request.

entries - The collection to which matching entries should be added.

references - The collection to which search result references should be added, or null if references are to be discarded.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

public ConnectionEntryReader search(String baseObject,
                                    SearchScope scope,
                                    String filter,
                                    String... attributeDescriptions)

Searches the Directory Server using the provided search parameters. Any matching entries returned by the search will be exposed through the EntryReader interface.

Warning: When using a queue with an optional capacity bound, the connection will stop reading responses and wait if necessary for space to become available.

This method is equivalent to the following code:

 
 SearchRequest request = new SearchRequest(baseDN, scope, filter, attributeDescriptions);
 connection.search(request, new LinkedBlockingQueue<Response>());
 
 

Parameters:

baseObject - The distinguished name of the base entry relative to which the search is to be performed.

scope - The scope of the search.

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

attributeDescriptions - The names of the attributes to be included with each entry.

Returns:

An entry reader exposing the returned entries.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the baseObject, scope, or filter were null.

searchSingleEntry

public SearchResultEntry searchSingleEntry(SearchRequest request)
                                    throws LdapException

Searches the Directory Server for a single entry using the provided search request.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

Parameters:

request - The search request.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the request was null.

searchSingleEntry

public SearchResultEntry searchSingleEntry(String baseObject,
                                           SearchScope scope,
                                           String filter,
                                           String... attributeDescriptions)
                                    throws LdapException

Searches the Directory Server for a single entry using the provided search parameters.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

This method is equivalent to the following code:

 
 SearchRequest request = new SearchRequest(baseObject, scope, filter, attributeDescriptions);
 connection.searchSingleEntry(request);
 
 

Parameters:

baseObject - The distinguished name of the base entry relative to which the search is to be performed.

scope - The scope of the search.

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

attributeDescriptions - The names of the attributes to be included with each entry.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

org.forgerock.i18n.LocalizedIllegalArgumentException - If baseObject could not be decoded using the default schema or if filter is not a valid LDAP string representation of a filter.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the baseObject, scope, or filter were null.