com.unboundid.ldap.listener

Class InMemoryRequestHandler

java.lang.Object

com.unboundid.ldap.listener.LDAPListenerRequestHandler

com.unboundid.ldap.listener.InMemoryRequestHandler

@Mutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class InMemoryRequestHandler
extends LDAPListenerRequestHandler

This class provides an implementation of an LDAP request handler that can be used to store entries in memory and process operations on those entries. It is primarily intended for use in creating a simple embeddable directory server that can be used for testing purposes. It performs only very basic validation, and is not intended to be a fully standards-compliant server.

Constructor Summary

Constructors

Constructor and Description
InMemoryRequestHandler(InMemoryDirectoryServerConfig config) Creates a new instance of this request handler with an initially-empty data set.

Method Summary

Modifier and Type	Method and Description
LDAPResult	add(AddRequest addRequest) Processes the provided add request.
void	addEntries(java.util.List<? extends Entry> entries) Attempts to add all of the provided entries to the server.
void	addEntry(Entry entry, boolean ignoreNoUserModification) Attempts to add the provided entry to the in-memory data set.
int	applyChangesFromLDIF(LDIFReader ldifReader) Reads entries from the provided LDIF reader and adds them to the server, optionally clearing any existing entries before beginning to add the new entries.
void	assertAttributeExists(java.lang.String dn, java.util.Collection<java.lang.String> attributeNames) Ensures that the specified entry exists in the directory with all of the specified attributes.
void	assertAttributeMissing(java.lang.String dn, java.util.Collection<java.lang.String> attributeNames) Ensures that the specified entry exists in the directory but does not contain any of the specified attributes.
void	assertEntriesExist(java.util.Collection<java.lang.String> dns) Ensures that all of the entries with the provided DNs exist in the directory.
void	assertEntryExists(Entry entry) Ensures that an entry exists in the directory with the same DN and all attribute values contained in the provided entry.
void	assertEntryExists(java.lang.String dn) Ensures that an entry with the provided DN exists in the directory.
void	assertEntryExists(java.lang.String dn, java.lang.String filter) Ensures that an entry with the provided DN exists in the directory.
void	assertEntryMissing(java.lang.String dn) Ensures that the specified entry does not exist in the directory.
void	assertValueExists(java.lang.String dn, java.lang.String attributeName, java.util.Collection<java.lang.String> attributeValues) Ensures that the specified entry exists in the directory with all of the specified values for the given attribute.
void	assertValueMissing(java.lang.String dn, java.lang.String attributeName, java.util.Collection<java.lang.String> attributeValues) Ensures that the specified entry exists in the directory but does not contain any of the specified attribute values.
void	clear() Removes all entries currently held in the server.
int	countEntries(boolean includeChangeLog) Retrieves the number of entries currently held in the server.
int	countEntriesBelow(java.lang.String baseDN) Retrieves the number of entries currently held in the server whose DN matches or is subordinate to the provided base DN.
InMemoryDirectoryServerSnapshot	createSnapshot() Creates a point-in-time snapshot of the information contained in this in-memory request handler.
LDAPResult	delete(DeleteRequest deleteRequest) Processes the provided delete request.
int	deleteSubtree(java.lang.String baseDN) Removes the entry with the specified DN and any subordinate entries it may have.
boolean	entryExists(Entry entry) Indicates whether the specified entry exists in the server.
boolean	entryExists(java.lang.String dn) Indicates whether the specified entry exists in the server.
boolean	entryExists(java.lang.String dn, java.lang.String filter) Indicates whether the specified entry exists in the server and matches the given filter.
int	exportToLDIF(LDIFWriter ldifWriter, boolean excludeGeneratedAttrs, boolean excludeChangeLog, boolean closeWriter) Writes all entries contained in the server to LDIF using the provided writer.
java.util.Map<DN,byte[]>	getAdditionalBindCredentials() Retrieves an unmodifiable map containing the defined set of additional bind credentials, mapped from bind DN to password bytes.
byte[]	getAdditionalBindCredentials(DN dn) Retrieves the password for the given DN from the set of additional bind credentials.
java.util.List<InMemoryPasswordEncoder>	getAllPasswordEncoders() Retrieves a list of all password encoders configured for the server.
DN	getAuthenticatedDN() Retrieves the DN of the user currently authenticated on the connection associated with this request handler instance.
java.util.List<DN>	getBaseDNs() Retrieves a list of the base DNs configured for use by the server.
LDAPListenerClientConnection	getClientConnection() Retrieves the client connection associated with this request handler instance.
java.util.Map<java.lang.String,java.lang.Object>	getConnectionState() Retrieves a map that may be used to hold state information specific to the connection associated with this request handler instance.
DN	getDNForAuthzID(java.lang.String authzID) Attempts to identify the DN of the user referenced by the provided authorization ID string.
ReadOnlyEntry	getEntry(DN dn) Retrieves a read-only representation the entry with the specified DN, if it exists.
ReadOnlyEntry	getEntry(java.lang.String dn) Retrieves a read-only representation the entry with the specified DN, if it exists.
java.util.List<java.lang.String>	getMissingAttributeNames(java.lang.String dn, java.util.Collection<java.lang.String> attributeNames) Retrieves a list containing all of the named attributes which do not exist in the target entry.
java.util.List<java.lang.String>	getMissingAttributeValues(java.lang.String dn, java.lang.String attributeName, java.util.Collection<java.lang.String> attributeValues) Retrieves a list of all provided attribute values which are missing from the specified entry.
java.util.List<java.lang.String>	getMissingEntryDNs(java.util.Collection<java.lang.String> dns) Retrieves a list containing the DNs of the entries which are missing from the directory server.
java.util.List<java.lang.String>	getPasswordAttributes() Retrieves the configured list of password attributes.
java.util.List<InMemoryDirectoryServerPassword>	getPasswordsInEntry(Entry entry, ASN1OctetString clearPasswordToMatch) Retrieves a list of the passwords contained in the provided entry.
InMemoryPasswordEncoder	getPrimaryPasswordEncoder() Retrieves the primary password encoder that has been configured for the server.
long	getProcessingDelayMillis() Retrieves the delay in milliseconds that the server should impose before beginning processing for operations.
Schema	getSchema() Retrieves the schema that will be used by the server, if any.
int	importFromLDIF(boolean clear, LDIFReader ldifReader) Reads entries from the provided LDIF reader and adds them to the server, optionally clearing any existing entries before beginning to add the new entries.
LDAPResult	modify(ModifyRequest modifyRequest) Processes the provided modify request.
LDAPResult	modifyDN(ModifyDNRequest modifyDNRequest) Processes the provided modify DN request.
void	modifyEntry(java.lang.String dn, java.util.List<Modification> mods) Attempts to apply the provided set of modifications to the specified entry.
InMemoryRequestHandler	newInstance(LDAPListenerClientConnection connection) Creates a new instance of this request handler that will be used to process requests read by the provided connection.
LDAPMessage	processAddRequest(int messageID, AddRequestProtocolOp request, java.util.List<Control> controls) Attempts to add an entry to the in-memory data set.
LDAPMessage	processBindRequest(int messageID, BindRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided bind request.
LDAPMessage	processCompareRequest(int messageID, CompareRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided compare request.
LDAPMessage	processDeleteRequest(int messageID, DeleteRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided delete request.
LDAPMessage	processExtendedRequest(int messageID, ExtendedRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided extended request, if an extended operation handler is defined for the given request OID.
LDAPMessage	processModifyDNRequest(int messageID, ModifyDNRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided modify DN request.
LDAPMessage	processModifyRequest(int messageID, ModifyRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided modify request.
LDAPMessage	processSearchRequest(int messageID, SearchRequestProtocolOp request, java.util.List<Control> controls) Attempts to process the provided search request.
void	restoreSnapshot(InMemoryDirectoryServerSnapshot snapshot) Updates the content of this in-memory request handler to match what it was at the time the snapshot was created.
java.util.List<ReadOnlyEntry>	search(java.lang.String baseDN, SearchScope scope, Filter filter) Retrieves a list of all entries in the server which match the given search criteria.
void	setAuthenticatedDN(DN authenticatedDN) Sets the DN of the user currently authenticated on the connection associated with this request handler instance.
void	setProcessingDelayMillis(long processingDelayMillis) Specifies the delay in milliseconds that the server should impose before beginning processing for operations.

Methods inherited from class com.unboundid.ldap.listener.LDAPListenerRequestHandler

closeInstance, processAbandonRequest, processUnbindRequest

Methods inherited from class java.lang.Object

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

Constructor Detail

InMemoryRequestHandler

public InMemoryRequestHandler(@NotNull
                              InMemoryDirectoryServerConfig config)
                       throws LDAPException

Creates a new instance of this request handler with an initially-empty data set.

Parameters:

config - The configuration that should be used for the in-memory directory server.

Throws:

LDAPException - If there is a problem with the provided configuration.

Method Detail

newInstance

@NotNull
public InMemoryRequestHandler newInstance(@NotNull
                                                   LDAPListenerClientConnection connection)
                                            throws LDAPException

Creates a new instance of this request handler that will be used to process requests read by the provided connection.

Specified by:

newInstance in class LDAPListenerRequestHandler

Parameters:

connection - The connection with which this request handler instance will be associated.

Returns:

The request handler instance that will be used for the provided connection.

Throws:

LDAPException - If the connection should not be accepted.

createSnapshot

@NotNull
public InMemoryDirectoryServerSnapshot createSnapshot()

Creates a point-in-time snapshot of the information contained in this in-memory request handler. If desired, it may be restored using the restoreSnapshot(com.unboundid.ldap.listener.InMemoryDirectoryServerSnapshot) method.

Returns:

The snapshot created based on the current content of this in-memory request handler.

restoreSnapshot

public void restoreSnapshot(@NotNull
                            InMemoryDirectoryServerSnapshot snapshot)

Updates the content of this in-memory request handler to match what it was at the time the snapshot was created.

Parameters:

snapshot - The snapshot to be restored. It must not be null.

getSchema

@Nullable
public Schema getSchema()

Retrieves the schema that will be used by the server, if any.

Returns:

The schema that will be used by the server, or null if none has been configured.

getBaseDNs

@NotNull
public java.util.List<DN> getBaseDNs()

Retrieves a list of the base DNs configured for use by the server.

Returns:

A list of the base DNs configured for use by the server.

getClientConnection

@Nullable
public LDAPListenerClientConnection getClientConnection()

Retrieves the client connection associated with this request handler instance.

Returns:

The client connection associated with this request handler instance, or null if this instance is not associated with any client connection.

getAuthenticatedDN

@NotNull
public DN getAuthenticatedDN()

Retrieves the DN of the user currently authenticated on the connection associated with this request handler instance.

Returns:

The DN of the user currently authenticated on the connection associated with this request handler instance, or DN#NULL_DN if the connection is unauthenticated or is authenticated as the anonymous user.

setAuthenticatedDN

public void setAuthenticatedDN(@Nullable
                               DN authenticatedDN)

Sets the DN of the user currently authenticated on the connection associated with this request handler instance.

Parameters:

authenticatedDN - The DN of the user currently authenticated on the connection associated with this request handler. It may be null or DN.NULL_DN to indicate that the connection is unauthenticated.

getAdditionalBindCredentials

@NotNull
public java.util.Map<DN,byte[]> getAdditionalBindCredentials()

Retrieves an unmodifiable map containing the defined set of additional bind credentials, mapped from bind DN to password bytes.

Returns:

An unmodifiable map containing the defined set of additional bind credentials, or an empty map if no additional credentials have been defined.

getAdditionalBindCredentials

@Nullable
public byte[] getAdditionalBindCredentials(@NotNull
                                                     DN dn)

Retrieves the password for the given DN from the set of additional bind credentials.

Parameters:

dn - The DN for which to retrieve the corresponding password.

Returns:

The password bytes for the given DN, or null if the additional bind credentials does not include information for the provided DN.

getConnectionState

@NotNull
public java.util.Map<java.lang.String,java.lang.Object> getConnectionState()

Retrieves a map that may be used to hold state information specific to the connection associated with this request handler instance. It may be queried and updated if necessary to store state information that may be needed at multiple different times in the life of a connection (e.g., when processing a multi-stage SASL bind).

Returns:

An updatable map that may be used to hold state information specific to the connection associated with this request handler instance.

getProcessingDelayMillis

public long getProcessingDelayMillis()

Retrieves the delay in milliseconds that the server should impose before beginning processing for operations.

Returns:

The delay in milliseconds that the server should impose before beginning processing for operations, or 0 if there should be no delay inserted when processing operations.

setProcessingDelayMillis

public void setProcessingDelayMillis(long processingDelayMillis)

Specifies the delay in milliseconds that the server should impose before beginning processing for operations.

Parameters:

processingDelayMillis - The delay in milliseconds that the server should impose before beginning processing for operations. A value less than or equal to zero may be used to indicate that there should be no delay.

add

@NotNull
public LDAPResult add(@NotNull
                               AddRequest addRequest)
                        throws LDAPException

Processes the provided add request.

This method may be used regardless of whether the server is listening for client connections, and regardless of whether add operations are allowed in the server.

Parameters:

addRequest - The add request to be processed. It must not be null.

Returns:

The result of processing the add operation.

Throws:

LDAPException - If the server rejects the add request, or if a problem is encountered while sending the request or reading the response.

processAddRequest

@NotNull
public LDAPMessage processAddRequest(int messageID,
                                              @NotNull
                                              AddRequestProtocolOp request,
                                              @NotNull
                                              java.util.List<Control> controls)

Attempts to add an entry to the in-memory data set. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The provided entry has a malformed DN.
• The provided entry has the null DN.
• The provided entry has a DN that is the same as or subordinate to the subschema subentry.
• The provided entry has a DN that is the same as or subordinate to the changelog base entry.
• An entry already exists with the same DN as the entry in the provided request.
• The entry is outside the set of base DNs for the server.
• The entry is below one of the defined base DNs but the immediate parent entry does not exist.
• If a schema was provided, and the entry is not valid according to the constraints of that schema.

Specified by:

processAddRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the add request.

request - The add request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be an AddResponseProtocolOp.

processBindRequest

@NotNull
public LDAPMessage processBindRequest(int messageID,
                                               @NotNull
                                               BindRequestProtocolOp request,
                                               @NotNull
                                               java.util.List<Control> controls)

Attempts to process the provided bind request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The bind request is for a SASL bind for which no SASL mechanism handler is defined.
• The bind request contains a malformed bind DN.
• The bind DN is not the null DN and is not the DN of any entry in the data set.
• The bind password is empty and the bind DN is not the null DN.
• The target user does not have any password value that matches the provided bind password.

Specified by:

processBindRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the bind request.

request - The bind request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be a BindResponseProtocolOp.

processCompareRequest

@NotNull
public LDAPMessage processCompareRequest(int messageID,
                                                  @NotNull
                                                  CompareRequestProtocolOp request,
                                                  @NotNull
                                                  java.util.List<Control> controls)

Attempts to process the provided compare request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The compare request contains a malformed target DN.
• The target entry does not exist.

Specified by:

processCompareRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the compare request.

request - The compare request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be a CompareResponseProtocolOp.

delete

@NotNull
public LDAPResult delete(@NotNull
                                  DeleteRequest deleteRequest)
                           throws LDAPException

Processes the provided delete request.

This method may be used regardless of whether the server is listening for client connections, and regardless of whether delete operations are allowed in the server.

Parameters:

deleteRequest - The delete request to be processed. It must not be null.

Returns:

The result of processing the delete operation.

Throws:

LDAPException - If the server rejects the delete request, or if a problem is encountered while sending the request or reading the response.

processDeleteRequest

@NotNull
public LDAPMessage processDeleteRequest(int messageID,
                                                 @NotNull
                                                 DeleteRequestProtocolOp request,
                                                 @NotNull
                                                 java.util.List<Control> controls)

Attempts to process the provided delete request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The delete request contains a malformed target DN.
• The target entry is the root DSE.
• The target entry is the subschema subentry.
• The target entry is at or below the changelog base entry.
• The target entry does not exist.
• The target entry has one or more subordinate entries.

Specified by:

processDeleteRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the delete request.

request - The delete request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be a DeleteResponseProtocolOp.

processExtendedRequest

@NotNull
public LDAPMessage processExtendedRequest(int messageID,
                                                   @NotNull
                                                   ExtendedRequestProtocolOp request,
                                                   @NotNull
                                                   java.util.List<Control> controls)

Attempts to process the provided extended request, if an extended operation handler is defined for the given request OID.

Specified by:

processExtendedRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the extended request.

request - The extended request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be an ExtendedResponseProtocolOp.

modify

@NotNull
public LDAPResult modify(@NotNull
                                  ModifyRequest modifyRequest)
                           throws LDAPException

Processes the provided modify request.

This method may be used regardless of whether the server is listening for client connections, and regardless of whether modify operations are allowed in the server.

Parameters:

modifyRequest - The modify request to be processed. It must not be null.

Returns:

The result of processing the modify operation.

Throws:

LDAPException - If the server rejects the modify request, or if a problem is encountered while sending the request or reading the response.

processModifyRequest

@NotNull
public LDAPMessage processModifyRequest(int messageID,
                                                 @NotNull
                                                 ModifyRequestProtocolOp request,
                                                 @NotNull
                                                 java.util.List<Control> controls)

Attempts to process the provided modify request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The modify request contains a malformed target DN.
• The target entry is the root DSE.
• The target entry is the subschema subentry.
• The target entry does not exist.
• Any of the modifications cannot be applied to the entry.
• If a schema was provided, and the entry violates any of the constraints of that schema.

Specified by:

processModifyRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the modify request.

request - The modify request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be an ModifyResponseProtocolOp.

modifyDN

@NotNull
public LDAPResult modifyDN(@NotNull
                                    ModifyDNRequest modifyDNRequest)
                             throws LDAPException

Processes the provided modify DN request.

This method may be used regardless of whether the server is listening for client connections, and regardless of whether modify DN operations are allowed in the server.

Parameters:

modifyDNRequest - The modify DN request to be processed. It must not be null.

Returns:

The result of processing the modify DN operation.

Throws:

LDAPException - If the server rejects the modify DN request, or if a problem is encountered while sending the request or reading the response.

processModifyDNRequest

@NotNull
public LDAPMessage processModifyDNRequest(int messageID,
                                                   @NotNull
                                                   ModifyDNRequestProtocolOp request,
                                                   @NotNull
                                                   java.util.List<Control> controls)

Attempts to process the provided modify DN request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The modify DN request contains a malformed target DN, new RDN, or new superior DN.
• The original or new DN is that of the root DSE.
• The original or new DN is that of the subschema subentry.
• The new DN of the entry would conflict with the DN of an existing entry.
• The new DN of the entry would exist outside the set of defined base DNs.
• The new DN of the entry is not a defined base DN and does not exist immediately below an existing entry.

Specified by:

processModifyDNRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the modify DN request.

request - The modify DN request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be an ModifyDNResponseProtocolOp.

processSearchRequest

@NotNull
public LDAPMessage processSearchRequest(int messageID,
                                                 @NotNull
                                                 SearchRequestProtocolOp request,
                                                 @NotNull
                                                 java.util.List<Control> controls)

Attempts to process the provided search request. The attempt will fail if any of the following conditions is true:

• There is a problem with any of the request controls.
• The modify DN request contains a malformed target DN, new RDN, or new superior DN.
• The new DN of the entry would conflict with the DN of an existing entry.
• The new DN of the entry would exist outside the set of defined base DNs.
• The new DN of the entry is not a defined base DN and does not exist immediately below an existing entry.

Specified by:

processSearchRequest in class LDAPListenerRequestHandler

Parameters:

messageID - The message ID of the LDAP message containing the search request.

request - The search request that was included in the LDAP message that was received.

controls - The set of controls included in the LDAP message. It may be empty if there were no controls, but will not be null.

Returns:

The LDAPMessage containing the response to send to the client. The protocol op in the LDAPMessage must be an SearchResultDoneProtocolOp.

getPasswordAttributes

@NotNull
public java.util.List<java.lang.String> getPasswordAttributes()

Retrieves the configured list of password attributes.

Returns:

The configured list of password attributes.

getPrimaryPasswordEncoder

@Nullable
public InMemoryPasswordEncoder getPrimaryPasswordEncoder()

Retrieves the primary password encoder that has been configured for the server.

Returns:

The primary password encoder that has been configured for the server.

getAllPasswordEncoders

@NotNull
public java.util.List<InMemoryPasswordEncoder> getAllPasswordEncoders()

Retrieves a list of all password encoders configured for the server.

Returns:

A list of all password encoders configured for the server.

getPasswordsInEntry

@NotNull
public java.util.List<InMemoryDirectoryServerPassword> getPasswordsInEntry(@NotNull
                                                                                    Entry entry,
                                                                                    @Nullable
                                                                                    ASN1OctetString clearPasswordToMatch)

Retrieves a list of the passwords contained in the provided entry.

Parameters:

entry - The entry from which to obtain the list of passwords. It must not be null.

clearPasswordToMatch - An optional clear-text password that should match the values that are returned. If this is null, then all passwords contained in the provided entry will be returned. If this is non-null, then only passwords matching the clear-text password will be returned.

Returns:

A list of the passwords contained in the provided entry, optionally restricted to those matching the provided clear-text password, or an empty list if the entry does not contain any passwords.

countEntries

public int countEntries(boolean includeChangeLog)

Retrieves the number of entries currently held in the server.

Parameters:

includeChangeLog - Indicates whether to include entries that are part of the changelog in the count.

Returns:

The number of entries currently held in the server.

countEntriesBelow

public int countEntriesBelow(@NotNull
                             java.lang.String baseDN)
                      throws LDAPException

Retrieves the number of entries currently held in the server whose DN matches or is subordinate to the provided base DN.

Parameters:

baseDN - The base DN to use for the determination.

Returns:

The number of entries currently held in the server whose DN matches or is subordinate to the provided base DN.

Throws:

LDAPException - If the provided string cannot be parsed as a valid DN.

clear

public void clear()

Removes all entries currently held in the server. If a changelog is enabled, then all changelog entries will also be cleared but the base "cn=changelog" entry will be retained.

importFromLDIF

public int importFromLDIF(boolean clear,
                          @NotNull
                          LDIFReader ldifReader)
                   throws LDAPException

Reads entries from the provided LDIF reader and adds them to the server, optionally clearing any existing entries before beginning to add the new entries. If an error is encountered while adding entries from LDIF then the server will remain populated with the data it held before the import attempt (even if the clear is given with a value of true).

Parameters:

clear - Indicates whether to remove all existing entries prior to adding entries read from LDIF.

ldifReader - The LDIF reader to use to obtain the entries to be imported. It will be closed by this method.

Returns:

The number of entries read from LDIF and added to the server.

Throws:

LDAPException - If a problem occurs while reading entries or adding them to the server.

exportToLDIF

public int exportToLDIF(@NotNull
                        LDIFWriter ldifWriter,
                        boolean excludeGeneratedAttrs,
                        boolean excludeChangeLog,
                        boolean closeWriter)
                 throws LDAPException

Writes all entries contained in the server to LDIF using the provided writer.

Parameters:

ldifWriter - The LDIF writer to use when writing the entries. It must not be null.

excludeGeneratedAttrs - Indicates whether to exclude automatically generated operational attributes like entryUUID, entryDN, creatorsName, etc.

excludeChangeLog - Indicates whether to exclude entries contained in the changelog.

closeWriter - Indicates whether the LDIF writer should be closed after all entries have been written.

Returns:

The number of entries written to LDIF.

Throws:

LDAPException - If a problem is encountered while attempting to write an entry to LDIF.

applyChangesFromLDIF

public int applyChangesFromLDIF(@NotNull
                                LDIFReader ldifReader)
                         throws LDAPException

Reads entries from the provided LDIF reader and adds them to the server, optionally clearing any existing entries before beginning to add the new entries. If an error is encountered while adding entries from LDIF then the server will remain populated with the data it held before the import attempt (even if the clear is given with a value of true).

This method may be used regardless of whether the server is listening for client connections.

Parameters:

ldifReader - The LDIF reader to use to obtain the change records to be applied.

Returns:

The number of changes applied from the LDIF file.

Throws:

LDAPException - If a problem occurs while reading change records or applying them to the server.

addEntry

public void addEntry(@NotNull
                     Entry entry,
                     boolean ignoreNoUserModification)
              throws LDAPException

Attempts to add the provided entry to the in-memory data set. The attempt will fail if any of the following conditions is true:

• The provided entry has a malformed DN.
• The provided entry has the null DN.
• The provided entry has a DN that is the same as or subordinate to the subschema subentry.
• An entry already exists with the same DN as the entry in the provided request.
• The entry is outside the set of base DNs for the server.
• The entry is below one of the defined base DNs but the immediate parent entry does not exist.
• If a schema was provided, and the entry is not valid according to the constraints of that schema.

Parameters:

entry - The entry to be added. It must not be null.

ignoreNoUserModification - Indicates whether to ignore constraints normally imposed by the NO-USER-MODIFICATION element in attribute type definitions.

Throws:

LDAPException - If a problem occurs while attempting to add the provided entry.

addEntries

public void addEntries(@NotNull
                       java.util.List<? extends Entry> entries)
                throws LDAPException

Attempts to add all of the provided entries to the server. If an error is encountered during processing, then the contents of the server will be the same as they were before this method was called.

Parameters:

entries - The collection of entries to be added.

Throws:

LDAPException - If a problem was encountered while attempting to add any of the entries to the server.

deleteSubtree

public int deleteSubtree(@NotNull
                         java.lang.String baseDN)
                  throws LDAPException

Removes the entry with the specified DN and any subordinate entries it may have.

Parameters:

baseDN - The DN of the entry to be deleted. It must not be null or represent the null DN.

Returns:

The number of entries actually removed, or zero if the specified base DN does not represent an entry in the server.

Throws:

LDAPException - If the provided base DN is not a valid DN, or is the DN of an entry that cannot be deleted (e.g., the null DN).

modifyEntry

public void modifyEntry(@NotNull
                        java.lang.String dn,
                        @NotNull
                        java.util.List<Modification> mods)
                 throws LDAPException

Attempts to apply the provided set of modifications to the specified entry. The attempt will fail if any of the following conditions is true:

• The target DN is malformed.
• The target entry is the root DSE.
• The target entry is the subschema subentry.
• The target entry does not exist.
• Any of the modifications cannot be applied to the entry.
• If a schema was provided, and the entry violates any of the constraints of that schema.

Parameters:

dn - The DN of the entry to be modified.

mods - The set of modifications to be applied to the entry.

Throws:

LDAPException - If a problem is encountered while attempting to update the specified entry.

getEntry

@Nullable
public ReadOnlyEntry getEntry(@NotNull
                                        java.lang.String dn)
                                 throws LDAPException

Retrieves a read-only representation the entry with the specified DN, if it exists.

Parameters:

dn - The DN of the entry to retrieve.

Returns:

The requested entry, or null if no entry exists with the given DN.

Throws:

LDAPException - If the provided DN is malformed.

getEntry

@Nullable
public ReadOnlyEntry getEntry(@NotNull
                                        DN dn)

Retrieves a read-only representation the entry with the specified DN, if it exists.

Parameters:

dn - The DN of the entry to retrieve.

Returns:

The requested entry, or null if no entry exists with the given DN.

search

@NotNull
public java.util.List<ReadOnlyEntry> search(@NotNull
                                                     java.lang.String baseDN,
                                                     @NotNull
                                                     SearchScope scope,
                                                     @NotNull
                                                     Filter filter)
                                              throws LDAPException

Retrieves a list of all entries in the server which match the given search criteria.

Parameters:

baseDN - The base DN to use for the search. It must not be null.

scope - The scope to use for the search. It must not be null.

filter - The filter to use for the search. It must not be null.

Returns:

A list of the entries that matched the provided search criteria.

Throws:

LDAPException - If a problem is encountered while performing the search.

getDNForAuthzID

@NotNull
public DN getDNForAuthzID(@NotNull
                                   java.lang.String authzID)
                            throws LDAPException

Attempts to identify the DN of the user referenced by the provided authorization ID string. It may be "dn:" followed by the target DN, or "u:" followed by the value of the uid attribute in the entry. If it uses the "dn:" form, then it may reference the DN of a regular entry or a DN in the configured set of additional bind credentials.

Parameters:

authzID - The authorization ID to resolve to a user DN.

Returns:

The DN identified for the provided authorization ID.

Throws:

LDAPException - If a problem prevents resolving the authorization ID to a user DN.

entryExists

public boolean entryExists(@NotNull
                           java.lang.String dn)
                    throws LDAPException

Indicates whether the specified entry exists in the server.

Parameters:

dn - The DN of the entry for which to make the determination.

Returns:

true if the entry exists, or false if not.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

entryExists

public boolean entryExists(@NotNull
                           java.lang.String dn,
                           @NotNull
                           java.lang.String filter)
                    throws LDAPException

Indicates whether the specified entry exists in the server and matches the given filter.

Parameters:

dn - The DN of the entry for which to make the determination.

filter - The filter the entry is expected to match.

Returns:

true if the entry exists and matches the specified filter, or false if not.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

entryExists

public boolean entryExists(@NotNull
                           Entry entry)
                    throws LDAPException

Indicates whether the specified entry exists in the server. This will return true only if the target entry exists and contains all values for all attributes of the provided entry. The entry will be allowed to have attribute values not included in the provided entry.

Parameters:

entry - The entry to compare against the directory server.

Returns:

true if the entry exists in the server and is a superset of the provided entry, or false if not.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

assertEntryExists

public void assertEntryExists(@NotNull
                              java.lang.String dn)
                       throws LDAPException,
                              java.lang.AssertionError

Ensures that an entry with the provided DN exists in the directory.

Parameters:

dn - The DN of the entry for which to make the determination.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry does not exist.

assertEntryExists

public void assertEntryExists(@NotNull
                              java.lang.String dn,
                              @NotNull
                              java.lang.String filter)
                       throws LDAPException,
                              java.lang.AssertionError

Ensures that an entry with the provided DN exists in the directory.

Parameters:

dn - The DN of the entry for which to make the determination.

filter - A filter that the target entry must match.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry does not exist or does not match the provided filter.

assertEntryExists

public void assertEntryExists(@NotNull
                              Entry entry)
                       throws LDAPException,
                              java.lang.AssertionError

Ensures that an entry exists in the directory with the same DN and all attribute values contained in the provided entry. The server entry may contain additional attributes and/or attribute values not included in the provided entry.

Parameters:

entry - The entry expected to be present in the directory server.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry does not exist or does not match the provided filter.

getMissingEntryDNs

@NotNull
public java.util.List<java.lang.String> getMissingEntryDNs(@NotNull
                                                                    java.util.Collection<java.lang.String> dns)
                                                             throws LDAPException

Retrieves a list containing the DNs of the entries which are missing from the directory server.

Parameters:

dns - The DNs of the entries to try to find in the server.

Returns:

A list containing all of the provided DNs that were not found in the server, or an empty list if all entries were found.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

assertEntriesExist

public void assertEntriesExist(@NotNull
                               java.util.Collection<java.lang.String> dns)
                        throws LDAPException,
                               java.lang.AssertionError

Ensures that all of the entries with the provided DNs exist in the directory.

Parameters:

dns - The DNs of the entries for which to make the determination.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If any of the target entries does not exist.

getMissingAttributeNames

@Nullable
public java.util.List<java.lang.String> getMissingAttributeNames(@NotNull
                                                                           java.lang.String dn,
                                                                           @NotNull
                                                                           java.util.Collection<java.lang.String> attributeNames)
                                                                    throws LDAPException

Retrieves a list containing all of the named attributes which do not exist in the target entry.

Parameters:

dn - The DN of the entry to examine.

attributeNames - The names of the attributes expected to be present in the target entry.

Returns:

A list containing the names of the attributes which were not present in the target entry, an empty list if all specified attributes were found in the entry, or null if the target entry does not exist.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

assertAttributeExists

public void assertAttributeExists(@NotNull
                                  java.lang.String dn,
                                  @NotNull
                                  java.util.Collection<java.lang.String> attributeNames)
                           throws LDAPException,
                                  java.lang.AssertionError

Ensures that the specified entry exists in the directory with all of the specified attributes.

Parameters:

dn - The DN of the entry to examine.

attributeNames - The names of the attributes that are expected to be present in the provided entry.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry does not exist or does not contain all of the specified attributes.

getMissingAttributeValues

@Nullable
public java.util.List<java.lang.String> getMissingAttributeValues(@NotNull
                                                                            java.lang.String dn,
                                                                            @NotNull
                                                                            java.lang.String attributeName,
                                                                            @NotNull
                                                                            java.util.Collection<java.lang.String> attributeValues)
                                                                     throws LDAPException

Retrieves a list of all provided attribute values which are missing from the specified entry. The target attribute may or may not contain additional values.

Parameters:

dn - The DN of the entry to examine.

attributeName - The attribute expected to be present in the target entry with the given values.

attributeValues - The values expected to be present in the target entry.

Returns:

A list containing all of the provided values which were not found in the entry, an empty list if all provided attribute values were found, or null if the target entry does not exist.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

assertValueExists

public void assertValueExists(@NotNull
                              java.lang.String dn,
                              @NotNull
                              java.lang.String attributeName,
                              @NotNull
                              java.util.Collection<java.lang.String> attributeValues)
                       throws LDAPException,
                              java.lang.AssertionError

Ensures that the specified entry exists in the directory with all of the specified values for the given attribute. The attribute may or may not contain additional values.

Parameters:

dn - The DN of the entry to examine.

attributeName - The name of the attribute to examine.

attributeValues - The set of values which must exist for the given attribute.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry does not exist, does not contain the specified attribute, or that attribute does not have all of the specified values.

assertEntryMissing

public void assertEntryMissing(@NotNull
                               java.lang.String dn)
                        throws LDAPException,
                               java.lang.AssertionError

Ensures that the specified entry does not exist in the directory.

Parameters:

dn - The DN of the entry expected to be missing.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry is found in the server.

assertAttributeMissing

public void assertAttributeMissing(@NotNull
                                   java.lang.String dn,
                                   @NotNull
                                   java.util.Collection<java.lang.String> attributeNames)
                            throws LDAPException,
                                   java.lang.AssertionError

Ensures that the specified entry exists in the directory but does not contain any of the specified attributes.

Parameters:

dn - The DN of the entry expected to be present.

attributeNames - The names of the attributes expected to be missing from the entry.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry is missing from the server, or if it contains any of the target attributes.

assertValueMissing

public void assertValueMissing(@NotNull
                               java.lang.String dn,
                               @NotNull
                               java.lang.String attributeName,
                               @NotNull
                               java.util.Collection<java.lang.String> attributeValues)
                        throws LDAPException,
                               java.lang.AssertionError

Ensures that the specified entry exists in the directory but does not contain any of the specified attribute values.

Parameters:

dn - The DN of the entry expected to be present.

attributeName - The name of the attribute to examine.

attributeValues - The values expected to be missing from the target entry.

Throws:

LDAPException - If a problem is encountered while trying to communicate with the directory server.

java.lang.AssertionError - If the target entry is missing from the server, or if it contains any of the target attribute values.