Class LDAPSortControl

java.lang.Object
netscape.ldap.LDAPControl
netscape.ldap.controls.LDAPSortControl
All Implemented Interfaces:
Serializable, Cloneable

public class LDAPSortControl extends LDAPControl
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.

Version:
1.0
See Also: