Class LDAPSortControl
- 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 theLDAPSortControl
constructor. TheLDAPSortKey
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 thesetServerControls
method. You can then pass thisLDAPSearchConstraints
object to thesearch
method of anLDAPConnection
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
andgetFailedAttribute
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:
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 responseLDAPSortControl
object.LDAPSortControl(LDAPSortKey[] keys, boolean critical)
Constructs anLDAPSortControl
object with an array of sorting keys.LDAPSortControl(LDAPSortKey key, boolean critical)
Constructs anLDAPSortControl
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
-
-
-
-
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 responseLDAPSortControl
object. This constructor is used byLDAPControl.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 beLDAPSortControl.SORTRESPONSE
or anLDAPException
is thrown.critical
-true
if this control is critical to the operationvalue
- the value associated with this control- Throws:
LDAPException
- If oid is notLDAPSortControl.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 anLDAPSortControl
object with a single sorting key.- Parameters:
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)- See Also:
LDAPControl
,LDAPSortKey
-
LDAPSortControl
public LDAPSortControl(LDAPSortKey[] keys, boolean critical)
Constructs anLDAPSortControl
object with an array of sorting keys.- Parameters:
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)- 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 theLDAPConnection
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 ofLDAPControl
objects, representing the controls returned by the server after a search. To get these controls, use thegetResponseControls
method of theLDAPConnection
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 classLDAPControl
- Returns:
- a string representation of the control.
-
-