Class LDAPSortControl
- All Implemented Interfaces:
Serializable
,Cloneable
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 |
|
No | None |
|
|
Yes | Yes | The server cannot sort the results using the specified sort key list. |
|
No |
|
||
N/A (could either be marked as critical or not) | The server successfully sorted the entries. |
|
|
The search itself failed (for any reason). |
|
-
Field Summary
FieldsFields inherited from class netscape.ldap.LDAPControl
m_critical, m_value, MANAGEDSAIT, PWEXPIRED, PWEXPIRING
-
Constructor Summary
ConstructorsConstructorDescriptionLDAPSortControl
(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
Modifier and TypeMethodDescriptionint
static String
parseResponse
(LDAPControl[] controls, int[] results) Deprecated.LDAPSortControl response controls are now automatically instantiated.toString()
Return a string representation of the control for debuggingMethods inherited from class netscape.ldap.LDAPControl
clone, createControl, flattenBER, getID, getValue, isCritical, lookupControlClass, newInstance, register
-
Field Details
-
SORTREQUEST
- See Also:
-
SORTRESPONSE
- See Also:
-
-
Constructor Details
-
LDAPSortControl
public LDAPSortControl(String oid, boolean critical, byte[] value) throws LDAPException, 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
.IOException
- If value contains an invalid BER sequence.- See Also:
-
LDAPSortControl
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:
-
LDAPSortControl
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:
-
-
Method Details
-
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.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:
-
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.
-