Class LDAPPersister<T>

  • Type Parameters:
    T - The type of object handled by this class.
    All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class LDAPPersister<T>
    extends java.lang.Object
    implements java.io.Serializable
    This class provides an interface that can be used to store and update representations of Java objects in an LDAP directory server, and to find and retrieve Java objects from the directory server. The objects to store, update, and retrieve must be marked with the LDAPObject annotation. Fields and methods within the class should be marked with the LDAPField, LDAPGetter, or LDAPSetter annotations as appropriate to indicate how to convert between the LDAP and the Java representations of the content.
    See Also:
    Serialized Form
    • Method Detail

      • getInstance

        public static <T> LDAPPersister<T> getInstance​(java.lang.Class<T> type)
                                                throws LDAPPersistException
        Retrieves an LDAPPersister instance for use with objects of the specified type.
        Type Parameters:
        T - The generic type for the LDAPPersister instance.
        Parameters:
        type - The type of object for which to retrieve the LDAP persister. It must not be null, and it must be marked with the LDAPObject annotation.
        Returns:
        The LDAPPersister instance for use with objects of the specified type.
        Throws:
        LDAPPersistException - If the provided class is not suitable for persisting in an LDAP directory server.
      • getLDAPObjectAnnotation

        public LDAPObject getLDAPObjectAnnotation()
        Retrieves the LDAPObject annotation of the class used for objects of the associated type.
        Returns:
        The LDAPObject annotation of the class used for objects of the associated type.
      • getObjectHandler

        public LDAPObjectHandler<TgetObjectHandler()
        Retrieves the LDAPObjectHandler instance associated with this LDAP persister class. It provides easy access to information about the LDAPObject annotation and the fields, getters, and setters used by the object.
        Returns:
        The LDAPObjectHandler instance associated with this LDAP persister class.
      • constructAttributeTypes

        public java.util.List<AttributeTypeDefinitionconstructAttributeTypes()
                                                                        throws LDAPPersistException
        Constructs a list of LDAP attribute type definitions which may be added to the directory server schema to allow it to hold objects of this type. Note that the object identifiers used for the constructed attribute type definitions are not required to be valid or unique.
        Returns:
        A list of attribute type definitions that may be used to represent objects of the associated type in an LDAP directory.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to generate the list of attribute type definitions.
      • constructAttributeTypes

        public java.util.List<AttributeTypeDefinitionconstructAttributeTypes​(OIDAllocator a)
                                                                        throws LDAPPersistException
        Constructs a list of LDAP attribute type definitions which may be added to the directory server schema to allow it to hold objects of this type. Note that the object identifiers used for the constructed attribute type definitions are not required to be valid or unique.
        Parameters:
        a - The OID allocator to use to generate the object identifiers for the constructed attribute types. It must not be null.
        Returns:
        A list of attribute type definitions that may be used to represent objects of the associated type in an LDAP directory.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to generate the list of attribute type definitions.
      • constructObjectClasses

        public java.util.List<ObjectClassDefinitionconstructObjectClasses()
                                                                     throws LDAPPersistException
        Constructs a list of LDAP object class definitions which may be added to the directory server schema to allow it to hold objects of this type. Note that the object identifiers used for the constructed object class definitions are not required to be valid or unique.
        Returns:
        A list of object class definitions that may be used to represent objects of the associated type in an LDAP directory.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to generate the list of object class definitions.
      • constructObjectClasses

        public java.util.List<ObjectClassDefinitionconstructObjectClasses​(OIDAllocator a)
                                                                     throws LDAPPersistException
        Constructs a list of LDAP object class definitions which may be added to the directory server schema to allow it to hold objects of this type. Note that the object identifiers used for the constructed object class definitions are not required to be valid or unique.
        Parameters:
        a - The OID allocator to use to generate the object identifiers for the constructed object classes. It must not be null.
        Returns:
        A list of object class definitions that may be used to represent objects of the associated type in an LDAP directory.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to generate the list of object class definitions.
      • updateSchema

        public boolean updateSchema​(LDAPInterface i)
                             throws LDAPException
        Attempts to update the schema for a directory server to ensure that it includes the attribute type and object class definitions used to store objects of the associated type. It will do this by attempting to add values to the attributeTypes and objectClasses attributes to the server schema. It will attempt to preserve existing schema elements.
        Parameters:
        i - The interface to use to communicate with the directory server.
        Returns:
        true if the schema was updated, or false if all of the necessary schema elements were already present.
        Throws:
        LDAPException - If an error occurs while attempting to update the server schema.
      • updateSchema

        public boolean updateSchema​(LDAPInterface i,
                                    OIDAllocator a)
                             throws LDAPException
        Attempts to update the schema for a directory server to ensure that it includes the attribute type and object class definitions used to store objects of the associated type. It will do this by attempting to add values to the attributeTypes and objectClasses attributes to the server schema. It will preserve existing attribute types, and will only modify existing object classes if the existing definition does not allow all of the attributes needed to store the associated object.

        Note that because there is no standard process for altering a directory server's schema over LDAP, the approach used by this method may not work for all types of directory servers. In addition, some directory servers may place restrictions on schema updates, particularly around the modification of existing schema elements. This method is provided as a convenience, but it may not work as expected in all environments or under all conditions.
        Parameters:
        i - The interface to use to communicate with the directory server.
        a - The OID allocator to use ot generate the object identifiers to use for the constructed attribute types and object classes. It must not be null.
        Returns:
        true if the schema was updated, or false if all of the necessary schema elements were already present.
        Throws:
        LDAPException - If an error occurs while attempting to update the server schema.
      • encode

        public Entry encode​(T o,
                            java.lang.String parentDN)
                     throws LDAPPersistException
        Encodes the provided object to an entry that is suitable for storing it in an LDAP directory server.
        Parameters:
        o - The object to be encoded. It must not be null.
        parentDN - The parent DN to use for the resulting entry. If the provided object was previously read from a directory server and includes a field marked with the LDAPDNField or LDAPEntryField annotation, then that field may be used to retrieve the actual DN of the associated entry. If the actual DN of the associated entry is not available, then a DN will be constructed from the RDN fields and/or getter methods declared in the class. If the provided parent DN is null, then the default parent DN defined in the LDAPObject annotation will be used.
        Returns:
        An entry containing the encoded representation of the provided object. It may be altered by the caller if necessary.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to encode the provided object.
      • decode

        public T decode​(Entry entry)
                 throws LDAPPersistException
        Creates an object and initializes it with the contents of the provided entry.
        Parameters:
        entry - The entry to use to create the object. It must not be null.
        Returns:
        The object created from the provided entry.
        Throws:
        LDAPPersistException - If an error occurs while attempting to create or initialize the object from the provided entry.
      • decode

        public void decode​(T o,
                           Entry entry)
                    throws LDAPPersistException
        Initializes the provided object from the information contained in the given entry.
        Parameters:
        o - The object to initialize with the contents of the provided entry. It must not be null.
        entry - The entry to use to create the object. It must not be null.
        Throws:
        LDAPPersistException - If an error occurs while attempting to initialize the object from the provided entry. If an exception is thrown, then the provided object may or may not have been altered.
      • add

        public LDAPResult add​(T o,
                              LDAPInterface i,
                              java.lang.String parentDN,
                              Control... controls)
                       throws LDAPPersistException
        Adds the provided object to the directory server using the provided connection.
        Parameters:
        o - The object to be added. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        parentDN - The parent DN to use for the resulting entry. If the provided object was previously read from a directory server and includes a field marked with the LDAPDNField or LDAPEntryField annotation, then that field may be used to retrieve the actual DN of the associated entry. If the actual DN of the associated entry is not available, then a DN will be constructed from the RDN fields and/or getter methods declared in the class. If the provided parent DN is null, then the default parent DN defined in the LDAPObject annotation will be used.
        controls - An optional set of controls to include in the add request.
        Returns:
        The result of processing the add operation.
        Throws:
        LDAPPersistException - If a problem occurs while encoding or adding the entry.
      • delete

        public LDAPResult delete​(T o,
                                 LDAPInterface i,
                                 Control... controls)
                          throws LDAPPersistException
        Deletes the provided object from the directory.
        Parameters:
        o - The object to be deleted. It must not be null, and it must have been retrieved from the directory and have a field with either the LDAPDNField or LDAPEntryField annotations.
        i - The interface to use to communicate with the directory server. It must not be null.
        controls - An optional set of controls to include in the add request.
        Returns:
        The result of processing the delete operation.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to delete the entry.
      • getModifications

        public java.util.List<ModificationgetModifications​(T o,
                                                             boolean deleteNullValues,
                                                             java.lang.String... attributes)
                                                      throws LDAPPersistException
        Retrieves a list of modifications that can be used to update the stored representation of the provided object in the directory. If the provided object was retrieved from the directory using the persistence framework and includes a field with the LDAPEntryField annotation, then that entry will be used to make the returned set of modifications as efficient as possible. Otherwise, the resulting modifications will include attempts to replace every attribute which are associated with fields or getters that should be used in modify operations.
        Parameters:
        o - The object for which to generate the list of modifications. It must not be null.
        deleteNullValues - Indicates whether to include modifications that may completely remove an attribute from the entry if the corresponding field or getter method has a value of null.
        attributes - The set of LDAP attributes for which to include modifications. If this is empty or null, then all attributes marked for inclusion in the modification will be examined.
        Returns:
        An unmodifiable list of modifications that can be used to update the stored representation of the provided object in the directory. It may be empty if there are no differences identified in the attributes to be evaluated.
        Throws:
        LDAPPersistException - If a problem occurs while computing the set of modifications.
      • getModifications

        public java.util.List<ModificationgetModifications​(T o,
                                                             boolean deleteNullValues,
                                                             boolean byteForByte,
                                                             java.lang.String... attributes)
                                                      throws LDAPPersistException
        Retrieves a list of modifications that can be used to update the stored representation of the provided object in the directory. If the provided object was retrieved from the directory using the persistence framework and includes a field with the LDAPEntryField annotation, then that entry will be used to make the returned set of modifications as efficient as possible. Otherwise, the resulting modifications will include attempts to replace every attribute which are associated with fields or getters that should be used in modify operations.
        Parameters:
        o - The object for which to generate the list of modifications. It must not be null.
        deleteNullValues - Indicates whether to include modifications that may completely remove an attribute from the entry if the corresponding field or getter method has a value of null.
        byteForByte - Indicates whether to use a byte-for-byte comparison to identify which attribute values have changed. Using byte-for-byte comparison requires additional processing over using each attribute's associated matching rule, but it can detect changes that would otherwise be considered logically equivalent (e.g., changing the capitalization of a value that uses a case-insensitive matching rule).
        attributes - The set of LDAP attributes for which to include modifications. If this is empty or null, then all attributes marked for inclusion in the modification will be examined.
        Returns:
        An unmodifiable list of modifications that can be used to update the stored representation of the provided object in the directory. It may be empty if there are no differences identified in the attributes to be evaluated.
        Throws:
        LDAPPersistException - If a problem occurs while computing the set of modifications.
      • modify

        public LDAPResult modify​(T o,
                                 LDAPInterface i,
                                 java.lang.String dn,
                                 boolean deleteNullValues,
                                 java.lang.String... attributes)
                          throws LDAPPersistException
        Updates the stored representation of the provided object in the directory. If the provided object was retrieved from the directory using the persistence framework and includes a field with the LDAPEntryField annotation, then that entry will be used to make the returned set of modifications as efficient as possible. Otherwise, the resulting modifications will include attempts to replace every attribute which are associated with fields or getters that should be used in modify operations. If there are no modifications, then no modification will be attempted, and this method will return null rather than an LDAPResult.
        Parameters:
        o - The object for which to generate the list of modifications. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        dn - The DN to use for the entry. It must not be null if the object was not retrieved from the directory using the persistence framework or does not have a field marked with the LDAPDNField or LDAPEntryField annotation.
        deleteNullValues - Indicates whether to include modifications that may completely remove an attribute from the entry if the corresponding field or getter method has a value of null.
        attributes - The set of LDAP attributes for which to include modifications. If this is empty or null, then all attributes marked for inclusion in the modification will be examined.
        Returns:
        The result of processing the modify operation, or null if there were no changes to apply (and therefore no modification was performed).
        Throws:
        LDAPPersistException - If a problem occurs while computing the set of modifications.
      • modify

        public LDAPResult modify​(T o,
                                 LDAPInterface i,
                                 java.lang.String dn,
                                 boolean deleteNullValues,
                                 java.lang.String[] attributes,
                                 Control... controls)
                          throws LDAPPersistException
        Updates the stored representation of the provided object in the directory. If the provided object was retrieved from the directory using the persistence framework and includes a field with the LDAPEntryField annotation, then that entry will be used to make the returned set of modifications as efficient as possible. Otherwise, the resulting modifications will include attempts to replace every attribute which are associated with fields or getters that should be used in modify operations. If there are no modifications, then no modification will be attempted, and this method will return null rather than an LDAPResult.
        Parameters:
        o - The object for which to generate the list of modifications. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        dn - The DN to use for the entry. It must not be null if the object was not retrieved from the directory using the persistence framework or does not have a field marked with the LDAPDNField or LDAPEntryField annotation.
        deleteNullValues - Indicates whether to include modifications that may completely remove an attribute from the entry if the corresponding field or getter method has a value of null.
        attributes - The set of LDAP attributes for which to include modifications. If this is empty or null, then all attributes marked for inclusion in the modification will be examined.
        controls - The optional set of controls to include in the modify request.
        Returns:
        The result of processing the modify operation, or null if there were no changes to apply (and therefore no modification was performed).
        Throws:
        LDAPPersistException - If a problem occurs while computing the set of modifications.
      • modify

        public LDAPResult modify​(T o,
                                 LDAPInterface i,
                                 java.lang.String dn,
                                 boolean deleteNullValues,
                                 boolean byteForByte,
                                 java.lang.String[] attributes,
                                 Control... controls)
                          throws LDAPPersistException
        Updates the stored representation of the provided object in the directory. If the provided object was retrieved from the directory using the persistence framework and includes a field with the LDAPEntryField annotation, then that entry will be used to make the returned set of modifications as efficient as possible. Otherwise, the resulting modifications will include attempts to replace every attribute which are associated with fields or getters that should be used in modify operations. If there are no modifications, then no modification will be attempted, and this method will return null rather than an LDAPResult.
        Parameters:
        o - The object for which to generate the list of modifications. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        dn - The DN to use for the entry. It must not be null if the object was not retrieved from the directory using the persistence framework or does not have a field marked with the LDAPDNField or LDAPEntryField annotation.
        deleteNullValues - Indicates whether to include modifications that may completely remove an attribute from the entry if the corresponding field or getter method has a value of null.
        byteForByte - Indicates whether to use a byte-for-byte comparison to identify which attribute values have changed. Using byte-for-byte comparison requires additional processing over using each attribute's associated matching rule, but it can detect changes that would otherwise be considered logically equivalent (e.g., changing the capitalization of a value that uses a case-insensitive matching rule).
        attributes - The set of LDAP attributes for which to include modifications. If this is empty or null, then all attributes marked for inclusion in the modification will be examined.
        controls - The optional set of controls to include in the modify request.
        Returns:
        The result of processing the modify operation, or null if there were no changes to apply (and therefore no modification was performed).
        Throws:
        LDAPPersistException - If a problem occurs while computing the set of modifications.
      • bind

        public BindResult bind​(T o,
                               java.lang.String baseDN,
                               java.lang.String password,
                               LDAPConnection c,
                               Control... controls)
                        throws LDAPException
        Attempts to perform a simple bind as the user specified by the given object on the provided connection. The object should represent some kind of entry capable suitable for use as the target of a simple bind operation.

        If the provided object was retrieved from the directory and has either an LDAPDNField or LDAPEntryField, then that field will be used to obtain the DN. Otherwise, a search will be performed to try to find the entry that corresponds to the provided object.
        Parameters:
        o - The object representing the user as whom to bind. It must not be null.
        baseDN - The base DN to use if it is necessary to search for the entry. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        password - The password to use for the bind. It must not be null.
        c - The connection to be authenticated. It must not be null.
        controls - An optional set of controls to include in the bind request. It may be empty or null if no controls are needed.
        Returns:
        The result of processing the bind operation.
        Throws:
        LDAPException - If a problem occurs while attempting to process the search or bind operation.
      • get

        public T get​(T o,
                     LDAPInterface i,
                     java.lang.String parentDN)
              throws LDAPPersistException
        Constructs the DN of the associated entry from the provided object and parent DN and retrieves the contents of that entry as a new instance of that object.
        Parameters:
        o - An object instance to use to construct the DN of the entry to retrieve. It must not be null, and all fields and/or getter methods marked for inclusion in the entry RDN must have non-null values.
        i - The interface to use to communicate with the directory server. It must not be null.
        parentDN - The parent DN to use for the entry to retrieve. If the provided object was previously read from a directory server and includes a field marked with the LDAPDNField or LDAPEntryField annotation, then that field may be used to retrieve the actual DN of the associated entry. If the actual DN of the target entry is not available, then a DN will be constructed from the RDN fields and/or getter methods declared in the class and this parent DN. If the provided parent DN is null, then the default parent DN defined in the LDAPObject annotation will be used.
        Returns:
        The object read from the entry with the provided DN, or null if no entry exists with the constructed DN.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to construct the entry DN, retrieve the corresponding entry or decode it as an object.
      • get

        public T get​(java.lang.String dn,
                     LDAPInterface i)
              throws LDAPPersistException
        Retrieves the object from the directory entry with the provided DN.
        Parameters:
        dn - The DN of the entry to retrieve and decode. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        Returns:
        The object read from the entry with the provided DN, or null if no entry exists with the provided DN.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to retrieve the specified entry or decode it as an object.
      • lazilyLoad

        public void lazilyLoad​(T o,
                               LDAPInterface i,
                               FieldInfo... fields)
                        throws LDAPPersistException
        Initializes any fields in the provided object marked for lazy loading.
        Parameters:
        o - The object to be updated. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        fields - The set of fields that should be loaded. Any fields included in this list which aren't marked for lazy loading will be ignored. If this is empty or null, then all lazily-loaded fields will be requested.
        Throws:
        LDAPPersistException - If a problem occurs while attempting to retrieve or process the associated entry. If an exception is thrown, then all content from the provided object that is not lazily loaded should remain valid, and some lazily-loaded fields may have been initialized.
      • search

        public PersistedObjects<Tsearch​(T o,
                                          LDAPConnection c)
                                   throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.

        The search performed will be a subtree search using a base DN equal to the LDAPObject.defaultParentDN() element in the LDAPObject annotation. It will not enforce a client-side time limit or size limit.

        Note that this method requires an LDAPConnection argument rather than using the more generic LDAPInterface type because the search is invoked as an asynchronous operation, which is not supported by the generic LDAPInterface interface. It also means that the provided connection must not be configured to operate in synchronous mode (via the LDAPConnectionOptions.setUseSynchronousMode(boolean) option).
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        c - The connection to use to communicate with the directory server. It must not be null.
        Returns:
        A results object that may be used to iterate through the objects returned from the search.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public PersistedObjects<Tsearch​(T o,
                                          LDAPConnection c,
                                          java.lang.String baseDN,
                                          SearchScope scope)
                                   throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.

        Note that this method requires an LDAPConnection argument rather than using the more generic LDAPInterface type because the search is invoked as an asynchronous operation, which is not supported by the generic LDAPInterface interface. It also means that the provided connection must not be configured to operate in synchronous mode (via the LDAPConnectionOptions.setUseSynchronousMode(boolean) option).
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        c - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        Returns:
        A results object that may be used to iterate through the objects returned from the search.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public PersistedObjects<Tsearch​(T o,
                                          LDAPConnection c,
                                          java.lang.String baseDN,
                                          SearchScope scope,
                                          DereferencePolicy derefPolicy,
                                          int sizeLimit,
                                          int timeLimit,
                                          Filter extraFilter,
                                          Control... controls)
                                   throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.

        Note that this method requires an LDAPConnection argument rather than using the more generic LDAPInterface type because the search is invoked as an asynchronous operation, which is not supported by the generic LDAPInterface interface. It also means that the provided connection must not be configured to operate in synchronous mode (via the LDAPConnectionOptions.setUseSynchronousMode(boolean) option).
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        c - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        derefPolicy - The dereference policy to use for the search operation. It must not be null.
        sizeLimit - The maximum number of entries to retrieve from the directory. A value of zero indicates that no client-requested size limit should be enforced.
        timeLimit - The maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that no client-requested time limit should be enforced.
        extraFilter - An optional additional filter to be ANDed with the filter generated from the provided object. If this is null, then only the filter generated from the object will be used.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        A results object that may be used to iterate through the objects returned from the search.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public SearchResult search​(T o,
                                   LDAPInterface i,
                                   ObjectSearchListener<T> l)
                            throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.

        The search performed will be a subtree search using a base DN equal to the LDAPObject.defaultParentDN() element in the LDAPObject annotation. It will not enforce a client-side time limit or size limit.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        l - The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not be null.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public SearchResult search​(T o,
                                   LDAPInterface i,
                                   java.lang.String baseDN,
                                   SearchScope scope,
                                   ObjectSearchListener<T> l)
                            throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        l - The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not be null.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public SearchResult search​(T o,
                                   LDAPInterface i,
                                   java.lang.String baseDN,
                                   SearchScope scope,
                                   DereferencePolicy derefPolicy,
                                   int sizeLimit,
                                   int timeLimit,
                                   Filter extraFilter,
                                   ObjectSearchListener<T> l,
                                   Control... controls)
                            throws LDAPPersistException
        Performs a search in the directory for objects matching the contents of the provided object. A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        derefPolicy - The dereference policy to use for the search operation. It must not be null.
        sizeLimit - The maximum number of entries to retrieve from the directory. A value of zero indicates that no client-requested size limit should be enforced.
        timeLimit - The maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that no client-requested time limit should be enforced.
        extraFilter - An optional additional filter to be ANDed with the filter generated from the provided object. If this is null, then only the filter generated from the object will be used.
        l - The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not be null.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public PersistedObjects<Tsearch​(LDAPConnection c,
                                          java.lang.String baseDN,
                                          SearchScope scope,
                                          DereferencePolicy derefPolicy,
                                          int sizeLimit,
                                          int timeLimit,
                                          Filter filter,
                                          Control... controls)
                                   throws LDAPPersistException
        Performs a search in the directory using the provided search criteria and decodes all entries returned as objects of the associated type.
        Parameters:
        c - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        derefPolicy - The dereference policy to use for the search operation. It must not be null.
        sizeLimit - The maximum number of entries to retrieve from the directory. A value of zero indicates that no client-requested size limit should be enforced.
        timeLimit - The maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that no client-requested time limit should be enforced.
        filter - The filter to use for the search. It must not be null. It will automatically be ANDed with a filter that will match entries with the structural and auxiliary classes.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • search

        public SearchResult search​(LDAPInterface i,
                                   java.lang.String baseDN,
                                   SearchScope scope,
                                   DereferencePolicy derefPolicy,
                                   int sizeLimit,
                                   int timeLimit,
                                   Filter filter,
                                   ObjectSearchListener<T> l,
                                   Control... controls)
                            throws LDAPPersistException
        Performs a search in the directory using the provided search criteria and decodes all entries returned as objects of the associated type.
        Parameters:
        i - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        derefPolicy - The dereference policy to use for the search operation. It must not be null.
        sizeLimit - The maximum number of entries to retrieve from the directory. A value of zero indicates that no client-requested size limit should be enforced.
        timeLimit - The maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that no client-requested time limit should be enforced.
        filter - The filter to use for the search. It must not be null. It will automatically be ANDed with a filter that will match entries with the structural and auxiliary classes.
        l - The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not be null.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.
      • searchForObject

        public T searchForObject​(T o,
                                 LDAPInterface i)
                          throws LDAPPersistException
        Performs a search in the directory to retrieve the object whose contents match the contents of the provided object. It is expected that at most one entry matches the provided criteria, and that it can be decoded as an object of the associated type. If multiple entries match the resulting criteria, or if the matching entry cannot be decoded as the associated type of object, then an exception will be thrown.

        A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.

        The search performed will be a subtree search using a base DN equal to the LDAPObject.defaultParentDN() element in the LDAPObject annotation. It will not enforce a client-side time limit or size limit.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        Returns:
        The object constructed from the entry returned by the search, or null if no entry was returned.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request or decoding the entry that was returned.
      • searchForObject

        public T searchForObject​(T o,
                                 LDAPInterface i,
                                 java.lang.String baseDN,
                                 SearchScope scope)
                          throws LDAPPersistException
        Performs a search in the directory to retrieve the object whose contents match the contents of the provided object. It is expected that at most one entry matches the provided criteria, and that it can be decoded as an object of the associated type. If multiple entries match the resulting criteria, or if the matching entry cannot be decoded as the associated type of object, then an exception will be thrown.

        A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The interface to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        Returns:
        The object constructed from the entry returned by the search, or null if no entry was returned.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request or decoding the entry that was returned.
      • searchForObject

        public T searchForObject​(T o,
                                 LDAPInterface i,
                                 java.lang.String baseDN,
                                 SearchScope scope,
                                 DereferencePolicy derefPolicy,
                                 int sizeLimit,
                                 int timeLimit,
                                 Filter extraFilter,
                                 Control... controls)
                          throws LDAPPersistException
        Performs a search in the directory to retrieve the object whose contents match the contents of the provided object. It is expected that at most one entry matches the provided criteria, and that it can be decoded as an object of the associated type. If multiple entries match the resulting criteria, or if the matching entry cannot be decoded as the associated type of object, then an exception will be thrown.

        A search filter will be generated from the provided object containing all non-null values from fields and getter methods whose LDAPField or LDAPGetter annotation has the inFilter element set to true.
        Parameters:
        o - The object to use to construct the search filter. It must not be null.
        i - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        scope - The scope to use for the search operation. It must not be null.
        derefPolicy - The dereference policy to use for the search operation. It must not be null.
        sizeLimit - The maximum number of entries to retrieve from the directory. A value of zero indicates that no client-requested size limit should be enforced.
        timeLimit - The maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that no client-requested time limit should be enforced.
        extraFilter - An optional additional filter to be ANDed with the filter generated from the provided object. If this is null, then only the filter generated from the object will be used.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        The object constructed from the entry returned by the search, or null if no entry was returned.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request or decoding the entry that was returned.
      • getAll

        public SearchResult getAll​(LDAPInterface i,
                                   java.lang.String baseDN,
                                   ObjectSearchListener<T> l,
                                   Control... controls)
                            throws LDAPPersistException
        Performs a search in the directory with an attempt to find all objects of the specified type below the given base DN (or below the default parent DN if no base DN is specified). Note that this may result in an unindexed search, which may be expensive to conduct. Some servers may require special permissions of clients wishing to perform unindexed searches.
        Parameters:
        i - The connection to use to communicate with the directory server. It must not be null.
        baseDN - The base DN to use for the search. It may be null if the LDAPObject.defaultParentDN() element in the LDAPObject should be used as the base DN.
        l - The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not be null.
        controls - An optional set of controls to include in the search request. It may be empty or null if no controls are needed.
        Returns:
        The result of the search operation that was processed.
        Throws:
        LDAPPersistException - If an error occurs while preparing or sending the search request.