com.novell.ldap
Class LDAPSearchConstraints

java.lang.Object
  com.novell.ldap.LDAPConstraints
      com.novell.ldap.LDAPSearchConstraints

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class LDAPSearchConstraints

extends LDAPConstraints

Defines the options controlling search operations.

An LDAPSearchConstraints object is always associated with an LDAPConnection object; its values can be changed with the LDAPConnection.setConstraints method, or overridden by passing an LDAPSearchConstraints object to the search operation.

Sample Code: Search.java

See Also:

LDAPConstraints, LDAPConnection.setConstraints(LDAPConstraints), Serialized Form

Field Summary

static int	DEREF_ALWAYS Indicates that aliases are always dereferenced, both when finding the starting point for the search, and also when searching the entries beneath the starting entry.
static int	DEREF_FINDING Indicates that aliases are dereferenced when finding the starting point for the search, but not when searching under that starting entry.
static int	DEREF_NEVER Indicates that aliases are never dereferenced.
static int	DEREF_SEARCHING Indicates that aliases are are derefrenced when searching the entries beneath the starting point of the search, but not when finding the starting entry.

Constructor Summary

LDAPSearchConstraints()
Constructs an LDAPSearchConstraints object with a default set of search constraints.

LDAPSearchConstraints(int msLimit, int serverTimeLimit, int dereference, int maxResults, boolean doReferrals, int batchSize, LDAPReferralHandler handler, int hop_limit)
Constructs a new LDAPSearchConstraints object and allows the specification operational constraints in that object.

LDAPSearchConstraints(LDAPConstraints cons)
Constructs an LDAPSearchConstraints object initialized with values from an existing constraints object (LDAPConstraints or LDAPSearchConstraints).

Method Summary

int	getBatchSize() Returns the number of results to block on during receipt of search results.
int	getDereference() Specifies when aliases should be dereferenced.
int	getMaxResults() Returns the maximum number of search results to be returned for a search operation.
int	getServerTimeLimit() Returns the maximum number of seconds that the server waits when returning search results.
void	setBatchSize(int batchSize) Specifies the number of results to return in a batch.
void	setDereference(int dereference) Sets a preference indicating whether or not aliases should be dereferenced, and if so, when.
void	setMaxResults(int maxResults) Sets the maximum number of search results to be returned from a search operation.
void	setServerTimeLimit(int seconds) Sets the maximum number of seconds that the server is to wait when returning search results.

Methods inherited from class com.novell.ldap.LDAPConstraints

clone, getControls, getHopLimit, getProperty, getReferralFollowing, getTimeLimit, setControls, setControls, setHopLimit, setProperty, setReferralFollowing, setReferralHandler, setTimeLimit

Methods inherited from class java.lang.Object

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

Field Detail

DEREF_NEVER

public static final int DEREF_NEVER

Indicates that aliases are never dereferenced.

DEREF_NEVER = 0

See Also:

getDereference(), setDereference(int), Constant Field Values

DEREF_SEARCHING

public static final int DEREF_SEARCHING

Indicates that aliases are are derefrenced when searching the entries beneath the starting point of the search, but not when finding the starting entry.

DEREF_SEARCHING = 1

See Also:

getDereference(), setDereference(int), Constant Field Values

DEREF_FINDING

public static final int DEREF_FINDING

Indicates that aliases are dereferenced when finding the starting point for the search, but not when searching under that starting entry.

DEREF_FINDING = 2

See Also:

getDereference(), setDereference(int), Constant Field Values

DEREF_ALWAYS

public static final int DEREF_ALWAYS

Indicates that aliases are always dereferenced, both when finding the starting point for the search, and also when searching the entries beneath the starting entry.

DEREF_ALWAYS = 3

See Also:

getDereference(), setDereference(int), Constant Field Values

Constructor Detail

LDAPSearchConstraints

public LDAPSearchConstraints()

Constructs an LDAPSearchConstraints object with a default set of search constraints.

LDAPSearchConstraints

public LDAPSearchConstraints(LDAPConstraints cons)

Constructs an LDAPSearchConstraints object initialized with values from an existing constraints object (LDAPConstraints or LDAPSearchConstraints).

LDAPSearchConstraints

public LDAPSearchConstraints(int msLimit,
                             int serverTimeLimit,
                             int dereference,
                             int maxResults,
                             boolean doReferrals,
                             int batchSize,
                             LDAPReferralHandler handler,
                             int hop_limit)

Constructs a new LDAPSearchConstraints object and allows the specification operational constraints in that object.

Parameters:

msLimit - The maximum time in milliseconds to wait for results. The default is 0, which means that there is no maximum time limit. This limit is enforced for an operation by the API, not by the server. The operation will be abandoned and terminated by the API with an LDAPException.LDAP_TIMEOUT if the operation exceeds the time limit.

serverTimeLimit - The maximum time in seconds that the server should spend returning search results. This is a server-enforced limit. The default of 0 means no time limit. The operation will be terminated by the server with an LDAPException.TIME_LIMIT_EXCEEDED if the search operation exceeds the time limit.

dereference - Specifies when aliases should be dereferenced. Must be either DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or DEREF_ALWAYS from this class. Default: DEREF_NEVER

maxResults - The maximum number of search results to return for a search request. The search operation will be terminated by the server with an LDAPException.SIZE_LIMIT_EXCEEDED if the number of results exceed the maximum. Default: 1000

doReferrals - Determines whether to automatically follow referrals or not. Specify true to follow referrals automatically, and false to throw an LDAPException.REFERRAL if the server responds with a referral. It is ignored for asynchronous operations. Default: false

batchSize - The number of results to return in a batch. Specifying 0 means to block until all results are received. Specifying 1 means to return results one result at a time. Default: 1

handler - The custom authentication handler called when LDAPConnection needs to authenticate, typically on following a referral. A null may be specified to indicate default authentication processing, i.e. referrals are followed with anonymous authentication. ThE object may be an implemention of either the the LDAPBindHandler or LDAPAuthHandler interface. It is ignored for asynchronous operations.

hop_limit - The maximum number of referrals to follow in a sequence during automatic referral following. The default value is 10. A value of 0 means no limit. It is ignored for asynchronous operations. The operation will be abandoned and terminated by the API with an LDAPException.REFERRAL_LIMIT_EXCEEDED if the number of referrals in a sequence exceeds the limit.

See Also:

LDAPException.LDAP_TIMEOUT, LDAPException.REFERRAL, LDAPException.SIZE_LIMIT_EXCEEDED, LDAPException.TIME_LIMIT_EXCEEDED

Method Detail

getBatchSize

public int getBatchSize()

Returns the number of results to block on during receipt of search results.

This should be 0 if intermediate reults are not needed, and 1 if results are to be processed as they come in. A value of indicates block until all results are received. Default:

Returns:

The the number of results to block on.

See Also:

setBatchSize(int)

getDereference

public int getDereference()

Specifies when aliases should be dereferenced.

Returns one of the following:

• DEREF_NEVER
• DEREF_FINDING
• DEREF_SEARCHING
• DEREF_ALWAYS

Returns:

The setting for dereferencing aliases.

See Also:

setDereference(int)

getMaxResults

public int getMaxResults()

Returns the maximum number of search results to be returned for a search operation. A value of 0 means no limit. Default: 1000 The search operation will be terminated with an LDAPException.SIZE_LIMIT_EXCEEDED if the number of results exceed the maximum.

Returns:

The value for the maximum number of results to return.

See Also:

setMaxResults(int), LDAPException.SIZE_LIMIT_EXCEEDED

getServerTimeLimit

public int getServerTimeLimit()

Returns the maximum number of seconds that the server waits when returning search results. The search operation will be terminated with an LDAPException.TIME_LIMIT_EXCEEDED if the operation exceeds the time limit.

Returns:

The maximum number of seconds the server waits for search' results.

See Also:

setServerTimeLimit(int), LDAPException.TIME_LIMIT_EXCEEDED

setBatchSize

public void setBatchSize(int batchSize)

Specifies the number of results to return in a batch.

Specifying 0 means to block until all results are received. Specifying 1 means to return results one result at a time. Default: 1

This should be 0 if intermediate results are not needed, and 1 if results are to be processed as they come in. The default is 1.

Parameters:

batchSize - The number of results to block on.

See Also:

getBatchSize()

setDereference

public void setDereference(int dereference)

Sets a preference indicating whether or not aliases should be dereferenced, and if so, when.

Parameters:

dereference - Specifies how aliases are dereference and can be set to one of the following:

• DEREF_NEVER - do not dereference aliases
• DEREF_FINDING - dereference aliases when finding the base object to start the search
• DEREF_SEARCHING - dereference aliases when searching but not when finding the base object to start the search
• DEREF_ALWAYS - dereference aliases when finding the base object and when searching

See Also:

getDereference()

setMaxResults

public void setMaxResults(int maxResults)

Sets the maximum number of search results to be returned from a search operation. The value 0 means no limit. The default is 1000. The search operation will be terminated with an LDAPException.SIZE_LIMIT_EXCEEDED if the number of results exceed the maximum.

Parameters:

maxResults - Maximum number of search results to return.

See Also:

getMaxResults(), LDAPException.SIZE_LIMIT_EXCEEDED

setServerTimeLimit

public void setServerTimeLimit(int seconds)

Sets the maximum number of seconds that the server is to wait when returning search results. The search operation will be terminated with an LDAPException.TIME_LIMIT_EXCEEDED if the operation exceeds the time limit.

The parameter is only recognized on search operations.

Parameters:

seconds - The number of seconds to wait for search results.

See Also:

getServerTimeLimit(), LDAPException.TIME_LIMIT_EXCEEDED