Represents an LDAP v3 server control that specifies that you want
the server to return sorted search results. (The OID for this
control is 1.2.840.113556.1.4.473.)
When constructing an
LDAPSortControl
object, you can
specify the order in which you want the results sorted.
You can also specify whether or not this control is critical
to the search operation.
To specify the sort order, you construct an
LDAPSortKey
object and pass it to the
LDAPSortControl
constructor.
The
LDAPSortKey
object represents a list of the attribute
types used for sorting (a "sort key list").
You can include the control in a search request by constructing
an
LDAPSearchConstraints
object and calling the
setServerControls
method. You can then pass this
LDAPSearchConstraints
object to the
search
method of an
LDAPConnection
object.
For example:
...
LDAPConnection ld = new LDAPConnection();
try {
// Connect to server.
ld.connect( 3, hostname, portnumber, "", "" );
// Create a sort key that specifies the sort order.
LDAPSortKey sortOrder = new LDAPSortKey( attrname );
// Create a "critical" server control using that sort key.
LDAPSortControl sortCtrl = new LDAPSortControl(sortOrder,true);
// Create search constraints to use that control.
LDAPSearchConstraints cons = new LDAPSearchConstraints();
cons.setServerControls( sortCtrl );
// Send the search request.
LDAPSearchResults res = ld.search( "o=Airius.com",
LDAPv3.SCOPE_SUB, "(cn=Barbara*)", null, false, cons );
...
The LDAP server sends back a sort response control to indicate
the result of the sorting operation. (The OID for this control
is 1.2.840.113556.1.4.474.)
This control contains:
- the result code from the sorting operation
- optionally, the first attribute type in the sort key list
that resulted in an error (for example, if the attribute does
not exist)
To retrieve the data from this control, use the
getResultCode
and
getFailedAttribute
methods.
The following table lists what kinds of results to expect from the
LDAP server under different situations:
Does the Server Support the Sorting Control? | Is the Sorting Control Marked As Critical? | Other Conditions | Results from LDAP Server |
---|
No
|
Yes
|
None
|
- The server does not send back any entries.
- An LDAPException.UNAVAILABLE_CRITICAL_EXTENSION
exception is thrown.
|
No
|
None
|
- The server ignores the sorting control and
returns the entries unsorted.
|
Yes
|
Yes
|
The server cannot sort the results using the specified
sort key list.
|
- The server does not send back any entries.
- An LDAPException.UNAVAILABLE_CRITICAL_EXTENSION
exception is thrown.
- The server sends back the sorting response control, which
specifies the result code of the sort attempt and (optionally)
the attribute type that caused the error.
|
No
|
- The server returns the entries unsorted.
- The server sends back the sorting response control, which
specifies the result code of the sort attempt and (optionally)
the attribute type that caused the error.
|
N/A (could either be marked as critical or not)
|
The server successfully sorted the entries.
|
- The server sends back the sorted entries.
- The server sends back the sorting response control, which
specifies the result code of the sort attempt
(LDAPException.SUCCESS).
|
The search itself failed (for any reason).
|
- The server sends back a result code for the search
operation.
- The server does not send back the sorting response control.
|
LDAPSortControl
public LDAPSortControl(String oid,
boolean critical,
byte[] value)
throws LDAPException,
IOException
Constructs a sort response
LDAPSortControl
object.
This constructor is used by
LDAPControl.register
to
instantiate sort response controls.
To retrieve the result code of the sort operation, call
getResultCode
.
To retrieve the attribute that caused the sort operation to fail, call
getFailedAttribute
.
oid
- the oid for this control. This must be
LDAPSortControl.SORTRESPONSE
or an LDAPException
is thrown.critical
- true
if this control is critical to the operationvalue
- the value associated with this control
LDAPSortControl
public LDAPSortControl(LDAPSortKey key,
boolean critical)
Constructs an LDAPSortControl
object with a single
sorting key.
key
- a single attribute by which to sortcritical
- true
if the LDAP operation should be
discarded when the server does not support this control (in other
words, this control is critical to the LDAP operation)
LDAPSortControl
public LDAPSortControl(LDAPSortKey[] keys,
boolean critical)
Constructs an LDAPSortControl
object with an array of
sorting keys.
keys
- the attributes by which to sortcritical
- true
if the LDAP operation should be
discarded when the server does not support this control (in other
words, this control is critical to the LDAP operation)