java.lang.Object
- netscape.ldap.LDAPControl
- - netscape.ldap.controls.LDAPSortControl

All Implemented Interfaces:: java.io.Serializable, java.lang.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	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).
	N/A (could either be marked as critical or not)	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:: LDAPSortKey, LDAPControl, LDAPConstraints, LDAPSearchConstraints, LDAPConstraints.setServerControls(LDAPControl), Serialized Form

Field Summary

Fields
Modifier and Type Field Description

static java.lang.String SORTREQUEST

static java.lang.String SORTRESPONSE
- Fields inherited from class netscape.ldap.LDAPControl
  m_critical, m_value, MANAGEDSAIT, PWEXPIRED, PWEXPIRING

Constructor Summary

Constructors
Constructor	Description
`LDAPSortControl(java.lang.String oid, boolean critical, byte[] value)`	Constructs a sort response `LDAPSortControl` object.
`LDAPSortControl(LDAPSortKey[] keys, boolean critical)`	Constructs an `LDAPSortControl` object with an array of sorting keys.
`LDAPSortControl(LDAPSortKey key, boolean critical)`	Constructs an `LDAPSortControl` object with a single sorting key.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`java.lang.String`	`getFailedAttribute()`
`int`	`getResultCode()`
`static java.lang.String`	`parseResponse(LDAPControl[] controls, int[] results)`	Deprecated. LDAPSortControl response controls are now automatically instantiated.
`java.lang.String`	`toString()`	Return a string representation of the control for debugging

Methods inherited from class netscape.ldap.LDAPControl
clone, createControl, flattenBER, getID, getValue, isCritical, lookupControlClass, newInstance, register

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SORTREQUEST

public static final java.lang.String SORTREQUEST

See Also:: Constant Field Values

SORTRESPONSE

public static final java.lang.String SORTRESPONSE

See Also:: Constant Field Values

Constructor Detail
- LDAPSortControl
```
public LDAPSortControl(java.lang.String oid,
                       boolean critical,
                       byte[] value)
                throws LDAPException,
                       java.io.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.
  
  Parameters:
  
  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 operation
  
  value - the value associated with this control
  
  Throws:
  
  LDAPException - If oid is not LDAPSortControl.SORTRESPONSE.
  
  java.io.IOException - If value contains an invalid BER sequence.
  
  See Also:
  
  LDAPControl.register(java.lang.String, java.lang.Class<?>)
- LDAPSortControl
```
public LDAPSortControl(LDAPSortKey key,
                       boolean critical)
```
  Constructs an LDAPSortControl object with a single sorting key.
  
  Parameters:
  
  key - a single attribute by which to sort
  
  critical - 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)
  
  See Also:
  
  LDAPControl, LDAPSortKey
- LDAPSortControl
```
public LDAPSortControl(LDAPSortKey[] keys,
                       boolean critical)
```
  Constructs an LDAPSortControl object with an array of sorting keys.
  
  Parameters:
  
  keys - the attributes by which to sort
  
  critical - 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)
  
  See Also:
  
  LDAPControl, LDAPSortKey

Method Detail

getFailedAttribute
```
public java.lang.String getFailedAttribute()
```
Returns:

the attribute that caused the sort operation to fail.

getResultCode
```
public int getResultCode()
```
Returns:

the result code from the search operation.

parseResponse

@Deprecated
public static java.lang.String parseResponse(LDAPControl[] controls,
                                             int[] results)

Deprecated.

LDAPSortControl response controls are now automatically instantiated.

Parses the sorting response control sent by the server and retrieves the result code from the sorting operation and the attribute that caused sorting to fail (if specified by the server).

You can get the controls returned by the server by using the getResponseControls method of the LDAPConnection class.

This method returns the attribute that caused the sort operation to fail (or null, if the server did not specify any attribute). The result code of the sorting operation is returned in the results argument. This argument is an array of integers; the result code is specified in the first element of this array.

For example:

 ...
 LDAPConnection ld = new LDAPConnection();
 try {
     // Connect to the server, set up the sorting control,
     // and set up the search constraints.
     ...

     // Search the directory.
     LDAPSearchResults res = ld.search( "o=Airius.com",
         LDAPv3.SCOPE_SUB, "(cn=Barbara*)", attrs, false, cons );

     // Determine if the server sent a control back to you.
     LDAPControl[] returnedControls = ld.getResponseControls();
     if ( returnedControls != null ) {
         int[] resultCodes = new int[1];
         String failedAttr = LDAPSortControl.parseResponse(
             returnedControls, resultCodes );

         // Check if the result code indicated an error occurred.
         if ( resultCodes[0] != 0 ) {
             System.out.println( "Result code: " + resultCodes[0] );
             if ( failedAttr != null ) {
                 System.out.println( "Sorting operation failed on " +
                     failedAttr );
             } else {
                 System.out.println( "Server did not indicate which " +
                     "attribute caused sorting to fail." );
             }
         }
     }
     ...
 }
 ...

The following table lists some of the possible result codes for the sorting operation.

`LDAPException.SUCCESS`	The server successfully sorted the results.
`LDAPException.OPERATION_ERROR`	An internal server error occurred.
`LDAPException.TIME_LIMIT_EXCEEDED`	The maximum time allowed for a search was exceeded before the server finished sorting the results.
`LDAPException.STRONG_AUTH_REQUIRED`	The server refused to send back the sorted search results because it requires you to use a stronger authentication method.
`LDAPException.ADMIN_LIMIT_EXCEEDED`	There are too many entries for the server to sort.
`LDAPException.NO_SUCH_ATTRIBUTE`	The sort key list specifies an attribute that does not exist.
`LDAPException.INAPPROPRIATE_MATCHING`	The sort key list specifies a matching rule that is not recognized or appropriate
`LDAPException.INSUFFICIENT_ACCESS_RIGHTS`	The server did not send the sorted results because the client has insufficient access rights.
`LDAPException.BUSY`	The server is too busy to sort the results.
`LDAPException.UNWILLING_TO_PERFORM`	The server is unable to sort the results.
`LDAPException.OTHER`	This general result code indicates that the server failed to sort the results for a reason other than the ones listed above.

Parameters:: controls - an array of LDAPControl objects, representing the controls returned by the server after a search. To get these controls, use the getResponseControls method of the LDAPConnection class.; results - an array of integers. The first element of this array specifies the result code of the sorting operation.
Returns:: the attribute that caused the error, or null if the server did not specify which attribute caused the error.
See Also:: LDAPConnection.getResponseControls()

toString
```
public java.lang.String toString()
```
Description copied from class: LDAPControl

Return a string representation of the control for debugging

Overrides:

toString in class LDAPControl

Returns:

a string representation of the control.

Modifier and Type	Field	Description
`static java.lang.String`	`SORTREQUEST`
`static java.lang.String`	`SORTRESPONSE`

Class LDAPSortControl

Field Summary

Fields inherited from class netscape.ldap.LDAPControl

Constructor Summary

Method Summary

Methods inherited from class netscape.ldap.LDAPControl

Methods inherited from class java.lang.Object

Field Detail

SORTREQUEST

SORTRESPONSE

Constructor Detail

LDAPSortControl

LDAPSortControl

LDAPSortControl

Method Detail

getFailedAttribute

getResultCode

parseResponse

toString