Class LDAPSearchConstraints
- All Implemented Interfaces:
Serializable
,Cloneable
LDAPSearchConstraints
object,
specifying your preferences, and passing the object to
the LDAPConnection.search
method.
- Version:
- 1.0
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Continue processing if there is an error following a search continuation referencestatic final int
Throw exception if there is an error following a search continuation reference -
Constructor Summary
ConstructorsConstructorDescriptionConstructs anLDAPSearchConstraints
object that specifies the default set of search constraints.LDAPSearchConstraints
(int msLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPRebind rebind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object.LDAPSearchConstraints
(int msLimit, int timeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPBind bind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object.LDAPSearchConstraints
(int msLimit, int timeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPRebind rebind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Makes a copy of an existing set of search constraints.int
Returns the suggested number of results to return at a time during search.int
Specifies how aliases should be dereferenced.int
Deprecated.int
Returns the maximum number of search results that are to be returned; 0 means there is no limit.int
Reports if errors when following search continuation references are to cause processing of the remaining results to be aborted.int
Returns the maximum number of seconds to wait for the server to spend on a search operation.If 0, there is no time limit.void
setBatchSize
(int batchSize) Sets the suggested number of results to return at a time during search.void
setDereference
(int dereference) Sets a preference indicating how aliases should be dereferenced.void
setMaxBacklog
(int backlog) Deprecated.UseLDAPConnection.setOption()
void
setMaxResults
(int maxResults) Sets the maximum number of search results to return; 0 means there is no limit.void
setReferralErrors
(int errorBehavior) Specifies if errors when following search continuation references are to cause processing of the remaining results to be aborted.void
setServerTimeLimit
(int limit) Sets the maximum number of seconds for the server to spend returning search results.toString()
Return a string representation of the object for debuggingMethods inherited from class netscape.ldap.LDAPConstraints
getBindProc, getClientControls, getHopLimit, getRebindProc, getReferrals, getServerControls, getTimeLimit, setBindProc, setClientControls, setClientControls, setHopLimit, setRebindProc, setReferrals, setServerControls, setServerControls, setTimeLimit
-
Field Details
-
REFERRAL_ERROR_CONTINUE
public static final int REFERRAL_ERROR_CONTINUEContinue processing if there is an error following a search continuation reference- See Also:
-
REFERRAL_ERROR_EXCEPTION
public static final int REFERRAL_ERROR_EXCEPTIONThrow exception if there is an error following a search continuation reference- See Also:
-
-
Constructor Details
-
LDAPSearchConstraints
public LDAPSearchConstraints()Constructs anLDAPSearchConstraints
object that specifies the default set of search constraints. -
LDAPSearchConstraints
public LDAPSearchConstraints(int msLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPRebind rebind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object.- Parameters:
msLimit
- maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit)dereference
- eitherLDAPv2.DEREF_NEVER
,LDAPv2.DEREF_FINDING
,LDAPv2.DEREF_SEARCHING
, orLDAPv2.DEREF_ALWAYS
(see LDAPConnection.setOption).LDAPv2.DEREF_NEVER
is the default.maxResults
- maximum number of search results to return (1000 by default)doReferrals
- specifytrue
to follow referrals automatically, orfalse
to throw anLDAPReferralException
error if the server sends back a referral (false
by default)batchSize
- specify the number of results to return at a time (1 by default)rebind_proc
- specifies the object of the class that implements theLDAPRebind
interface (you need to define this class). The object will be used when the client follows referrals automatically. The object provides the client with a method for getting the distinguished name and password used to authenticate to another LDAP server during a referral. (This field isnull
by default.)hop_limit
- maximum number of referrals to follow in a sequence when attempting to resolve a request- See Also:
-
LDAPSearchConstraints
public LDAPSearchConstraints(int msLimit, int timeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPRebind rebind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object.- Parameters:
msLimit
- maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit)timeLimit
- maximum time in seconds for the server to spend processing a search request (the default value is 0, indicating that there is no limit)dereference
- eitherLDAPv2.DEREF_NEVER
,LDAPv2.DEREF_FINDING
,LDAPv2.DEREF_SEARCHING
, orLDAPv2.DEREF_ALWAYS
(see LDAPConnection.setOption).LDAPv2.DEREF_NEVER
is the default.maxResults
- maximum number of search results to return (1000 by default)doReferrals
- specifytrue
to follow referrals automatically, orfalse
to throw anLDAPReferralException
error if the server sends back a referral (false
by default)batchSize
- specify the number of results to return at a time (1 by default)rebind_proc
- specifies the object that implements theLDAPRebind
interface. The object will be used when the client follows referrals automatically. The object provides the client with a method for getting the distinguished name and password used to authenticate to another LDAP server during a referral. (This field isnull
by default.)hop_limit
- maximum number of referrals to follow in a sequence when attempting to resolve a request- See Also:
-
LDAPSearchConstraints
public LDAPSearchConstraints(int msLimit, int timeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPBind bind_proc, int hop_limit) Constructs a newLDAPSearchConstraints
object and allows you to specify the search constraints in that object.- Parameters:
msLimit
- maximum time in milliseconds to wait for results (0 by default, which means that there is no maximum time limit)timeLimit
- maximum time in seconds for the server to spend processing a search request (the default value is 0, indicating that there is no limit)dereference
- eitherLDAPv2.DEREF_NEVER
,LDAPv2.DEREF_FINDING
,LDAPv2.DEREF_SEARCHING
, orLDAPv2.DEREF_ALWAYS
(see LDAPConnection.setOption).LDAPv2.DEREF_NEVER
is the default.maxResults
- maximum number of search results to return (1000 by default)doReferrals
- specifytrue
to follow referrals automatically, orfalse
to throw anLDAPReferralException
error if the server sends back a referral (false
by default)batchSize
- specify the number of results to return at a time (1 by default)bind_proc
- specifies the object that implements theLDAPBind
interface (you need to define this class). The object will be used to authenticate to the server on referrals. (This field isnull
by default.)hop_limit
- maximum number of referrals to follow in a sequence when attempting to resolve a request- See Also:
-
-
Method Details
-
getServerTimeLimit
public int getServerTimeLimit()Returns the maximum number of seconds to wait for the server to spend on a search operation.If 0, there is no time limit.- Returns:
- maximum number of seconds for the server to spend.
-
getDereference
public int getDereference()Specifies how aliases should be dereferenced.- Returns:
LDAPv2.DEREF_NEVER
to never follow ("dereference") aliases,LDAPv2.DEREF_FINDING
to dereference when finding the starting point for the search (but not when searching under that starting entry),LDAPv2.DEREF_SEARCHING
to dereference when searching the entries beneath the starting point of the search (but not when finding the starting entry), orLDAPv2.DEREF_ALWAYS
to always dereference aliases.
-
getMaxResults
public int getMaxResults()Returns the maximum number of search results that are to be returned; 0 means there is no limit.- Returns:
- maximum number of search results to be returned.
-
getBatchSize
public int getBatchSize()Returns the suggested number of results to return at a time during search. This should be 0 if intermediate results are not needed, and 1 if results are to be processed as they come in.- Returns:
- number of results to return at a time.
-
setServerTimeLimit
public void setServerTimeLimit(int limit) Sets the maximum number of seconds for the server to spend returning search results. If 0, there is no time limit.- Parameters:
limit
- maximum number of seconds for the server to spend. (0 by default, which means that there is no maximum time limit.)
-
setDereference
public void setDereference(int dereference) Sets a preference indicating how aliases should be dereferenced.- Parameters:
dereference
-LDAPv2.DEREF_NEVER
to never follow ("dereference") aliases,LDAPv2.DEREF_FINDING
to dereference when finding the starting point for the search (but not when searching under that starting entry),LDAPv2.DEREF_SEARCHING
to dereference when searching the entries beneath the starting point of the search (but not when finding the starting entry), orLDAPv2.DEREF_ALWAYS
to always dereference aliases
-
setMaxResults
public void setMaxResults(int maxResults) Sets the maximum number of search results to return; 0 means there is no limit. (By default, this is set to 1000.)- Parameters:
maxResults
- maximum number of search results to return
-
setBatchSize
public void setBatchSize(int batchSize) Sets the suggested number of results to return at a time during search. This should be 0 if intermediate results are not needed, and 1 if results are to be processed as they come in. (By default, this is 1.)- Parameters:
batchSize
- number of results to return at a time
-
setMaxBacklog
Deprecated.UseLDAPConnection.setOption()
Set the maximum number of unread entries any search listener can have before we stop reading from the server.- Parameters:
backlog
- the maximum number of unread entries per listener
-
getMaxBacklog
Deprecated.UseLDAPConnection.getOption()
Get the maximum number of unread entries any search listener can have before we stop reading from the server.- Returns:
- the maximum number of unread entries per listener.
-
getReferralErrors
public int getReferralErrors()Reports if errors when following search continuation references are to cause processing of the remaining results to be aborted.If an LDAP server does not contain an entry at the base DN for a search, it may be configured to return a referral. If it contains an entry at the base DN of a subtree search, one or more of the child entries may contain search continuation references. The search continuation references are returned to the client, which may follow them by issuing a search request to the host indicated in the search reference.
If the
LDAPConnection
object has been configured to follow referrals automatically, it may fail when issuing a search request to the host indicated in a search reference, e.g. because there is no entry there, because it does not have credentials, because it does not have sufficient permissions, etc. If the client aborts evaluation of the search results (obtained throughLDAPSearchResults
) when a search reference cannot be followed, any remaining results are discarded.Up to version 4.17 of the Java LDAP SDK, the SDK printed an error message but continued to process the remaining search results and search continuation references.
As of SDK version 4.17, the default behavior is still to continue processing any remaining search results and search continuation references if there is an error following a referral, but the behavior may be changed with
setReferralErrors
to throw an exception instead.- Returns:
REFERRAL_ERROR_CONTINUE
if remaining results are to be processed when there is an error following a search continuation reference,REFERRAL_ERROR_EXCEPTION
if such an error is to cause anLDAPException
.- Since:
- LDAPJDK 4.17
- See Also:
-
setReferralErrors
public void setReferralErrors(int errorBehavior) Specifies if errors when following search continuation references are to cause processing of the remaining results to be aborted.If an LDAP server does not contain an entry at the base DN for a search, it may be configured to return a referral. If it contains an entry at the base DN of a subtree search, one or more of the child entries may contain search continuation references. The search continuation references are returned to the client, which may follow them by issuing a search request to the host indicated in the search reference.
If the
LDAPConnection
object has been configured to follow referrals automatically, it may fail when issuing a search request to the host indicated in a search reference, e.g. because there is no entry there, because it does not have credentials, because it does not have sufficient permissions, etc. If the client aborts evaluation of the search results (obtained throughLDAPSearchResults
) when a search reference cannot be followed, any remaining results are discarded.Up to version 4.17 of the Java LDAP SDK, the SDK printed an error message but continued to process the remaining search results and search continuation references.
As of SDK version 4.17, the default behavior is still to continue processing any remaining search results and search continuation references if there is an error following a referral, but the behavior may be changed with
setReferralErrors
to throw an exception instead.- Parameters:
errorBehavior
- EitherREFERRAL_ERROR_CONTINUE
if remaining results are to be processed when there is an error following a search continuation reference orREFERRAL_ERROR_EXCEPTION
if such an error is to cause anLDAPException
.- Since:
- LDAPJDK 4.17
- See Also:
-
clone
Makes a copy of an existing set of search constraints.- Overrides:
clone
in classLDAPConstraints
- Returns:
- a copy of an existing set of search constraints.
-
toString
Return a string representation of the object for debugging- Overrides:
toString
in classLDAPConstraints
- Returns:
- A string representation of the object
-
LDAPConnection.getOption()