Package 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 theLDAPObject
annotation. Fields and methods within the class should be marked with theLDAPField
,LDAPGetter
, orLDAPSetter
annotations as appropriate to indicate how to convert between the LDAP and the Java representations of the content.- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 anLDAPPersister
instance for use with objects of the specified type.LDAPObject
getLDAPObjectAnnotation()
Retrieves theLDAPObject
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 theLDAPObjectHandler
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.
-
-
-
Method Detail
-
getInstance
public static <T> LDAPPersister<T> getInstance(java.lang.Class<T> type) throws LDAPPersistException
Retrieves anLDAPPersister
instance for use with objects of the specified type.- Type Parameters:
T
- The generic type for theLDAPPersister
instance.- Parameters:
type
- The type of object for which to retrieve the LDAP persister. It must not benull
, and it must be marked with theLDAPObject
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 theLDAPObject
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<T> getObjectHandler()
Retrieves theLDAPObjectHandler
instance associated with this LDAP persister class. It provides easy access to information about theLDAPObject
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<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
public java.util.List<AttributeTypeDefinition> constructAttributeTypes(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 benull
.- 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<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
public java.util.List<ObjectClassDefinition> constructObjectClasses(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 benull
.- 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, orfalse
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 benull
.- Returns:
true
if the schema was updated, orfalse
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 benull
.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 theLDAPDNField
orLDAPEntryField
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 isnull
, then the default parent DN defined in theLDAPObject
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 benull
.- 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 benull
.entry
- The entry to use to create the object. It must not benull
.- 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 benull
.i
- The interface to use to communicate with the directory server. It must not benull
.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 theLDAPDNField
orLDAPEntryField
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 isnull
, then the default parent DN defined in theLDAPObject
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 benull
, and it must have been retrieved from the directory and have a field with either theLDAPDNField
orLDAPEntryField
annotations.i
- The interface to use to communicate with the directory server. It must not benull
.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<Modification> getModifications(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 theLDAPEntryField
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 benull
.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 ofnull
.attributes
- The set of LDAP attributes for which to include modifications. If this is empty ornull
, 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<Modification> getModifications(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 theLDAPEntryField
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 benull
.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 ofnull
.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 ornull
, 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 theLDAPEntryField
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 returnnull
rather than anLDAPResult
.- Parameters:
o
- The object for which to generate the list of modifications. It must not benull
.i
- The interface to use to communicate with the directory server. It must not benull
.dn
- The DN to use for the entry. It must not benull
if the object was not retrieved from the directory using the persistence framework or does not have a field marked with theLDAPDNField
orLDAPEntryField
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 ofnull
.attributes
- The set of LDAP attributes for which to include modifications. If this is empty ornull
, 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 theLDAPEntryField
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 returnnull
rather than anLDAPResult
.- Parameters:
o
- The object for which to generate the list of modifications. It must not benull
.i
- The interface to use to communicate with the directory server. It must not benull
.dn
- The DN to use for the entry. It must not benull
if the object was not retrieved from the directory using the persistence framework or does not have a field marked with theLDAPDNField
orLDAPEntryField
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 ofnull
.attributes
- The set of LDAP attributes for which to include modifications. If this is empty ornull
, 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 theLDAPEntryField
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 returnnull
rather than anLDAPResult
.- Parameters:
o
- The object for which to generate the list of modifications. It must not benull
.i
- The interface to use to communicate with the directory server. It must not benull
.dn
- The DN to use for the entry. It must not benull
if the object was not retrieved from the directory using the persistence framework or does not have a field marked with theLDAPDNField
orLDAPEntryField
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 ofnull
.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 ornull
, 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 anLDAPDNField
orLDAPEntryField
, 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 benull
.baseDN
- The base DN to use if it is necessary to search for the entry. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.password
- The password to use for the bind. It must not benull
.c
- The connection to be authenticated. It must not benull
.controls
- An optional set of controls to include in the bind request. It may be empty ornull
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 benull
, 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 benull
.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 theLDAPDNField
orLDAPEntryField
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 isnull
, then the default parent DN defined in theLDAPObject
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 benull
.i
- The interface to use to communicate with the directory server. It must not benull
.- 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 benull
.i
- The interface to use to communicate with the directory server. It must not benull
.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 ornull
, 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<T> search(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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.
The search performed will be a subtree search using a base DN equal to theLDAPObject.defaultParentDN()
element in theLDAPObject
annotation. It will not enforce a client-side time limit or size limit.
Note that this method requires anLDAPConnection
argument rather than using the more genericLDAPInterface
type because the search is invoked as an asynchronous operation, which is not supported by the genericLDAPInterface
interface. It also means that the provided connection must not be configured to operate in synchronous mode (via theLDAPConnectionOptions.setUseSynchronousMode(boolean)
option).- Parameters:
o
- The object to use to construct the search filter. It must not benull
.c
- The connection to use to communicate with the directory server. It must not benull
.- 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<T> search(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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.
Note that this method requires anLDAPConnection
argument rather than using the more genericLDAPInterface
type because the search is invoked as an asynchronous operation, which is not supported by the genericLDAPInterface
interface. It also means that the provided connection must not be configured to operate in synchronous mode (via theLDAPConnectionOptions.setUseSynchronousMode(boolean)
option).- Parameters:
o
- The object to use to construct the search filter. It must not benull
.c
- The connection to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.- 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<T> search(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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.
Note that this method requires anLDAPConnection
argument rather than using the more genericLDAPInterface
type because the search is invoked as an asynchronous operation, which is not supported by the genericLDAPInterface
interface. It also means that the provided connection must not be configured to operate in synchronous mode (via theLDAPConnectionOptions.setUseSynchronousMode(boolean)
option).- Parameters:
o
- The object to use to construct the search filter. It must not benull
.c
- The connection to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.derefPolicy
- The dereference policy to use for the search operation. It must not benull
.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 isnull
, 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 ornull
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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.
The search performed will be a subtree search using a base DN equal to theLDAPObject.defaultParentDN()
element in theLDAPObject
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 benull
.i
- The interface to use to communicate with the directory server. It must not benull
.l
- The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not benull
.- 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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.- Parameters:
o
- The object to use to construct the search filter. It must not benull
.i
- The interface to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.l
- The object search result listener that will be used to receive objects decoded from entries returned for the search. It must not benull
.- 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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.- Parameters:
o
- The object to use to construct the search filter. It must not benull
.i
- The connection to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.derefPolicy
- The dereference policy to use for the search operation. It must not benull
.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 isnull
, 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 benull
.controls
- An optional set of controls to include in the search request. It may be empty ornull
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<T> search(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 benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.derefPolicy
- The dereference policy to use for the search operation. It must not benull
.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 benull
. 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 ornull
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 benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.derefPolicy
- The dereference policy to use for the search operation. It must not benull
.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 benull
. 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 benull
.controls
- An optional set of controls to include in the search request. It may be empty ornull
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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.
The search performed will be a subtree search using a base DN equal to theLDAPObject.defaultParentDN()
element in theLDAPObject
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 benull
.i
- The interface to use to communicate with the directory server. It must not benull
.- 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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.- Parameters:
o
- The object to use to construct the search filter. It must not benull
.i
- The interface to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.- 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 whoseLDAPField
orLDAPGetter
annotation has theinFilter
element set totrue
.- Parameters:
o
- The object to use to construct the search filter. It must not benull
.i
- The connection to use to communicate with the directory server. It must not benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
should be used as the base DN.scope
- The scope to use for the search operation. It must not benull
.derefPolicy
- The dereference policy to use for the search operation. It must not benull
.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 isnull
, 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 ornull
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 benull
.baseDN
- The base DN to use for the search. It may benull
if theLDAPObject.defaultParentDN()
element in theLDAPObject
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 benull
.controls
- An optional set of controls to include in the search request. It may be empty ornull
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.
-
-