netscape.ldap.controls
Class LDAPSortControl

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

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.

See Also:

LDAPSortKey, LDAPControl, LDAPConstraints, LDAPSearchConstraints, LDAPConstraints.setServerControls(LDAPControl)

Field Summary

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

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.

LDAPSortControl(java.lang.String oid, boolean critical, byte[] value)
Constructs a sort response LDAPSortControl object.

Method Summary

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

SORTRESPONSE

public static final java.lang.String SORTRESPONSE

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

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

Tags copied from class: LDAPControl

Returns:

a string representation of the control.