com.unboundid.ldap.sdk.persist

Class LDAPPersister<T>

java.lang.Object

com.unboundid.ldap.sdk.persist.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 Summary

Modifier and Type	Method and Description
LDAPResult	add(T o, LDAPInterface i, java.lang.String parentDN, Control... controls) Adds the provided object to the directory server using the provided connection.
BindResult	bind(T o, java.lang.String baseDN, java.lang.String password, LDAPConnection c, Control... controls) Attempts to perform a simple bind as the user specified by the given object on the provided connection.
java.util.List<AttributeTypeDefinition>	constructAttributeTypes() 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.
java.util.List<AttributeTypeDefinition>	constructAttributeTypes(OIDAllocator a) 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.
java.util.List<ObjectClassDefinition>	constructObjectClasses() 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.
java.util.List<ObjectClassDefinition>	constructObjectClasses(OIDAllocator a) 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.
T	decode(Entry entry) Creates an object and initializes it with the contents of the provided entry.
void	decode(T o, Entry entry) Initializes the provided object from the information contained in the given entry.
LDAPResult	delete(T o, LDAPInterface i, Control... controls) Deletes the provided object from the directory.
Entry	encode(T o, java.lang.String parentDN) Encodes the provided object to an entry that is suitable for storing it in an LDAP directory server.
T	get(java.lang.String dn, LDAPInterface i) Retrieves the object from the directory entry with the provided DN.
T	get(T o, LDAPInterface i, java.lang.String parentDN) 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.
SearchResult	getAll(LDAPInterface i, java.lang.String baseDN, ObjectSearchListener<T> l, Control... controls) 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).
static <T> LDAPPersister<T>	getInstance(java.lang.Class<T> type) Retrieves an LDAPPersister instance for use with objects of the specified type.
LDAPObject	getLDAPObjectAnnotation() Retrieves the LDAPObject annotation of the class used for objects of the associated type.
java.util.List<Modification>	getModifications(T o, boolean deleteNullValues, boolean byteForByte, java.lang.String... attributes) Retrieves a list of modifications that can be used to update the stored representation of the provided object in the directory.
java.util.List<Modification>	getModifications(T o, boolean deleteNullValues, java.lang.String... attributes) Retrieves a list of modifications that can be used to update the stored representation of the provided object in the directory.
LDAPObjectHandler<T>	getObjectHandler() Retrieves the LDAPObjectHandler instance associated with this LDAP persister class.
void	lazilyLoad(T o, LDAPInterface i, FieldInfo... fields) Initializes any fields in the provided object marked for lazy loading.
LDAPResult	modify(T o, LDAPInterface i, java.lang.String dn, boolean deleteNullValues, boolean byteForByte, java.lang.String[] attributes, Control... controls) Updates the stored representation of the provided object in the directory.
LDAPResult	modify(T o, LDAPInterface i, java.lang.String dn, boolean deleteNullValues, java.lang.String... attributes) Updates the stored representation of the provided object in the directory.
LDAPResult	modify(T o, LDAPInterface i, java.lang.String dn, boolean deleteNullValues, java.lang.String[] attributes, Control... controls) Updates the stored representation of the provided object in the directory.
PersistedObjects<T>	search(LDAPConnection c, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, Filter filter, Control... controls) Performs a search in the directory using the provided search criteria and decodes all entries returned as objects of the associated type.
SearchResult	search(LDAPInterface i, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, Filter filter, ObjectSearchListener<T> l, Control... controls) Performs a search in the directory using the provided search criteria and decodes all entries returned as objects of the associated type.
PersistedObjects<T>	search(T o, LDAPConnection c) Performs a search in the directory for objects matching the contents of the provided object.
PersistedObjects<T>	search(T o, LDAPConnection c, java.lang.String baseDN, SearchScope scope) Performs a search in the directory for objects matching the contents of the provided object.
PersistedObjects<T>	search(T o, LDAPConnection c, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, Filter extraFilter, Control... controls) Performs a search in the directory for objects matching the contents of the provided object.
SearchResult	search(T o, LDAPInterface i, ObjectSearchListener<T> l) Performs a search in the directory for objects matching the contents of the provided object.
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) Performs a search in the directory for objects matching the contents of the provided object.
SearchResult	search(T o, LDAPInterface i, java.lang.String baseDN, SearchScope scope, ObjectSearchListener<T> l) Performs a search in the directory for objects matching the contents of the provided object.
T	searchForObject(T o, LDAPInterface i) Performs a search in the directory to retrieve the object whose contents match the contents of the provided object.
T	searchForObject(T o, LDAPInterface i, java.lang.String baseDN, SearchScope scope) Performs a search in the directory to retrieve the object whose contents match the contents of the provided object.
T	searchForObject(T o, LDAPInterface i, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, Filter extraFilter, Control... controls) Performs a search in the directory to retrieve the object whose contents match the contents of the provided object.
boolean	updateSchema(LDAPInterface i) 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.
boolean	updateSchema(LDAPInterface i, OIDAllocator a) 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.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

@NotNull
public static <T> LDAPPersister<T> getInstance(@NotNull
                                                        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

@NotNull
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

@NotNull
public LDAPObjectHandler<T> getObjectHandler()

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

@NotNull
public java.util.List<AttributeTypeDefinition> constructAttributeTypes()
                                                                         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

@NotNull
public java.util.List<AttributeTypeDefinition> constructAttributeTypes(@NotNull
                                                                                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

@NotNull
public java.util.List<ObjectClassDefinition> constructObjectClasses()
                                                                      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

@NotNull
public java.util.List<ObjectClassDefinition> constructObjectClasses(@NotNull
                                                                             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(@NotNull
                            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(@NotNull
                            LDAPInterface i,
                            @NotNull
                            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

@NotNull
public Entry encode(@NotNull
                             T o,
                             @Nullable
                             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

@NotNull
public T decode(@NotNull
                         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(@NotNull
                   T o,
                   @NotNull
                   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

@NotNull
public LDAPResult add(@NotNull
                               T o,
                               @NotNull
                               LDAPInterface i,
                               @Nullable
                               java.lang.String parentDN,
                               @Nullable
                               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

@NotNull
public LDAPResult delete(@NotNull
                                  T o,
                                  @NotNull
                                  LDAPInterface i,
                                  @Nullable
                                  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

@NotNull
public java.util.List<Modification> getModifications(@NotNull
                                                              T o,
                                                              boolean deleteNullValues,
                                                              @Nullable
                                                              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

@NotNull
public java.util.List<Modification> getModifications(@NotNull
                                                              T o,
                                                              boolean deleteNullValues,
                                                              boolean byteForByte,
                                                              @Nullable
                                                              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

@NotNull
public LDAPResult modify(@NotNull
                                  T o,
                                  @NotNull
                                  LDAPInterface i,
                                  @Nullable
                                  java.lang.String dn,
                                  boolean deleteNullValues,
                                  @Nullable
                                  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

@NotNull
public LDAPResult modify(@NotNull
                                  T o,
                                  @NotNull
                                  LDAPInterface i,
                                  @Nullable
                                  java.lang.String dn,
                                  boolean deleteNullValues,
                                  @Nullable
                                  java.lang.String[] attributes,
                                  @Nullable
                                  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

@Nullable
public LDAPResult modify(@NotNull
                                   T o,
                                   @NotNull
                                   LDAPInterface i,
                                   @Nullable
                                   java.lang.String dn,
                                   boolean deleteNullValues,
                                   boolean byteForByte,
                                   @Nullable
                                   java.lang.String[] attributes,
                                   @Nullable
                                   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

@NotNull
public BindResult bind(@NotNull
                                T o,
                                @Nullable
                                java.lang.String baseDN,
                                @NotNull
                                java.lang.String password,
                                @NotNull
                                LDAPConnection c,
                                @Nullable
                                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

@Nullable
public T get(@NotNull
                       T o,
                       @NotNull
                       LDAPInterface i,
                       @Nullable
                       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

@Nullable
public T get(@NotNull
                       java.lang.String dn,
                       @NotNull
                       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(@NotNull
                       T o,
                       @NotNull
                       LDAPInterface i,
                       @Nullable
                       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

@NotNull
public PersistedObjects<T> search(@NotNull
                                           T o,
                                           @NotNull
                                           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

@NotNull
public PersistedObjects<T> search(@NotNull
                                           T o,
                                           @NotNull
                                           LDAPConnection c,
                                           @Nullable
                                           java.lang.String baseDN,
                                           @NotNull
                                           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

@NotNull
public PersistedObjects<T> search(@NotNull
                                           T o,
                                           @NotNull
                                           LDAPConnection c,
                                           @Nullable
                                           java.lang.String baseDN,
                                           @NotNull
                                           SearchScope scope,
                                           @NotNull
                                           DereferencePolicy derefPolicy,
                                           int sizeLimit,
                                           int timeLimit,
                                           @Nullable
                                           Filter extraFilter,
                                           @Nullable
                                           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

@NotNull
public SearchResult search(@NotNull
                                    T o,
                                    @NotNull
                                    LDAPInterface i,
                                    @NotNull
                                    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

@NotNull
public SearchResult search(@NotNull
                                    T o,
                                    @NotNull
                                    LDAPInterface i,
                                    @Nullable
                                    java.lang.String baseDN,
                                    @NotNull
                                    SearchScope scope,
                                    @NotNull
                                    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

@NotNull
public SearchResult search(@NotNull
                                    T o,
                                    @NotNull
                                    LDAPInterface i,
                                    @Nullable
                                    java.lang.String baseDN,
                                    @NotNull
                                    SearchScope scope,
                                    @NotNull
                                    DereferencePolicy derefPolicy,
                                    int sizeLimit,
                                    int timeLimit,
                                    @Nullable
                                    Filter extraFilter,
                                    @NotNull
                                    ObjectSearchListener<T> l,
                                    @Nullable
                                    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

@NotNull
public PersistedObjects<T> search(@NotNull
                                           LDAPConnection c,
                                           @Nullable
                                           java.lang.String baseDN,
                                           @NotNull
                                           SearchScope scope,
                                           @NotNull
                                           DereferencePolicy derefPolicy,
                                           int sizeLimit,
                                           int timeLimit,
                                           @NotNull
                                           Filter filter,
                                           @Nullable
                                           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

@NotNull
public SearchResult search(@NotNull
                                    LDAPInterface i,
                                    @Nullable
                                    java.lang.String baseDN,
                                    @NotNull
                                    SearchScope scope,
                                    @NotNull
                                    DereferencePolicy derefPolicy,
                                    int sizeLimit,
                                    int timeLimit,
                                    @NotNull
                                    Filter filter,
                                    @NotNull
                                    ObjectSearchListener<T> l,
                                    @Nullable
                                    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

@Nullable
public T searchForObject(@NotNull
                                   T o,
                                   @NotNull
                                   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

@Nullable
public T searchForObject(@NotNull
                                   T o,
                                   @NotNull
                                   LDAPInterface i,
                                   @Nullable
                                   java.lang.String baseDN,
                                   @NotNull
                                   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

@Nullable
public T searchForObject(@NotNull
                                   T o,
                                   @NotNull
                                   LDAPInterface i,
                                   @Nullable
                                   java.lang.String baseDN,
                                   @NotNull
                                   SearchScope scope,
                                   @NotNull
                                   DereferencePolicy derefPolicy,
                                   int sizeLimit,
                                   int timeLimit,
                                   @Nullable
                                   Filter extraFilter,
                                   @Nullable
                                   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

@NotNull
public SearchResult getAll(@NotNull
                                    LDAPInterface i,
                                    @Nullable
                                    java.lang.String baseDN,
                                    @NotNull
                                    ObjectSearchListener<T> l,
                                    @Nullable
                                    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.