Class 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.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • 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<DNgetBaseDNs()
        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.
      • getPasswordsInEntry

        @NotNull
        public java.util.List<InMemoryDirectoryServerPasswordgetPasswordsInEntry​(@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<ReadOnlyEntrysearch​(@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.