23 * questions.
24 */
25
26 package javax.naming.ldap;
27
28 import java.io.IOException;
29 import com.sun.jndi.ldap.Ber;
30 import com.sun.jndi.ldap.BerEncoder;
31
32 /**
33 * Requests that the results of a search operation be sorted by the LDAP server
34 * before being returned.
35 * The sort criteria are specified using an ordered list of one or more sort
36 * keys, with associated sort parameters.
37 * Search results are sorted at the LDAP server according to the parameters
38 * supplied in the sort control and then returned to the requestor. If sorting
39 * is not supported at the server (and the sort control is marked as critical)
40 * then the search operation is not performed and an error is returned.
41 * <p>
42 * The following code sample shows how the class may be used:
43 * <pre>
44 *
45 * // Open an LDAP association
46 * LdapContext ctx = new InitialLdapContext();
47 *
48 * // Activate sorting
49 * String sortKey = "cn";
50 * ctx.setRequestControls(new Control[]{
51 * new SortControl(sortKey, Control.CRITICAL) });
52 *
53 * // Perform a search
54 * NamingEnumeration results =
55 * ctx.search("", "(objectclass=*)", new SearchControls());
56 *
57 * // Iterate over search results
58 * while (results != null && results.hasMore()) {
59 * // Display an entry
60 * SearchResult entry = (SearchResult)results.next();
61 * System.out.println(entry.getName());
62 * System.out.println(entry.getAttributes());
63 *
68 * }
69 * // Examine the sort control response
70 * Control[] controls = ctx.getResponseControls();
71 * if (controls != null) {
72 * for (int i = 0; i < controls.length; i++) {
73 * if (controls[i] instanceof SortResponseControl) {
74 * SortResponseControl src = (SortResponseControl)controls[i];
75 * if (! src.isSorted()) {
76 * throw src.getException();
77 * }
78 * } else {
79 * // Handle other response controls (if any)
80 * }
81 * }
82 * }
83 *
84 * // Close the LDAP association
85 * ctx.close();
86 * ...
87 *
88 * </pre>
89 * <p>
90 * This class implements the LDAPv3 Request Control for server-side sorting
91 * as defined in
92 * <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
93 *
94 * The control's value has the following ASN.1 definition:
95 * <pre>
96 *
97 * SortKeyList ::= SEQUENCE OF SEQUENCE {
98 * attributeType AttributeDescription,
99 * orderingRule [0] MatchingRuleId OPTIONAL,
100 * reverseOrder [1] BOOLEAN DEFAULT FALSE }
101 *
102 * </pre>
103 *
104 * @since 1.5
105 * @see SortKey
106 * @see SortResponseControl
107 * @author Vincent Ryan
108 */
|
23 * questions.
24 */
25
26 package javax.naming.ldap;
27
28 import java.io.IOException;
29 import com.sun.jndi.ldap.Ber;
30 import com.sun.jndi.ldap.BerEncoder;
31
32 /**
33 * Requests that the results of a search operation be sorted by the LDAP server
34 * before being returned.
35 * The sort criteria are specified using an ordered list of one or more sort
36 * keys, with associated sort parameters.
37 * Search results are sorted at the LDAP server according to the parameters
38 * supplied in the sort control and then returned to the requestor. If sorting
39 * is not supported at the server (and the sort control is marked as critical)
40 * then the search operation is not performed and an error is returned.
41 * <p>
42 * The following code sample shows how the class may be used:
43 * <pre>{@code
44 *
45 * // Open an LDAP association
46 * LdapContext ctx = new InitialLdapContext();
47 *
48 * // Activate sorting
49 * String sortKey = "cn";
50 * ctx.setRequestControls(new Control[]{
51 * new SortControl(sortKey, Control.CRITICAL) });
52 *
53 * // Perform a search
54 * NamingEnumeration results =
55 * ctx.search("", "(objectclass=*)", new SearchControls());
56 *
57 * // Iterate over search results
58 * while (results != null && results.hasMore()) {
59 * // Display an entry
60 * SearchResult entry = (SearchResult)results.next();
61 * System.out.println(entry.getName());
62 * System.out.println(entry.getAttributes());
63 *
68 * }
69 * // Examine the sort control response
70 * Control[] controls = ctx.getResponseControls();
71 * if (controls != null) {
72 * for (int i = 0; i < controls.length; i++) {
73 * if (controls[i] instanceof SortResponseControl) {
74 * SortResponseControl src = (SortResponseControl)controls[i];
75 * if (! src.isSorted()) {
76 * throw src.getException();
77 * }
78 * } else {
79 * // Handle other response controls (if any)
80 * }
81 * }
82 * }
83 *
84 * // Close the LDAP association
85 * ctx.close();
86 * ...
87 *
88 * }</pre>
89 * <p>
90 * This class implements the LDAPv3 Request Control for server-side sorting
91 * as defined in
92 * <a href="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
93 *
94 * The control's value has the following ASN.1 definition:
95 * <pre>
96 *
97 * SortKeyList ::= SEQUENCE OF SEQUENCE {
98 * attributeType AttributeDescription,
99 * orderingRule [0] MatchingRuleId OPTIONAL,
100 * reverseOrder [1] BOOLEAN DEFAULT FALSE }
101 *
102 * </pre>
103 *
104 * @since 1.5
105 * @see SortKey
106 * @see SortResponseControl
107 * @author Vincent Ryan
108 */
|