SortControl


1   /*
2    * @(#)SortControl.java 1.3 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.naming.ldap;
9   
10  import java.io.IOException  ;
11  import com.sun.jndi.ldap.Ber;
12  import com.sun.jndi.ldap.BerEncoder;
13  
14  /**
15   * Requests that the results of a search operation be sorted by the LDAP server
16   * before being returned. 
17   * The sort criteria are specified using an ordered list of one or more sort 
18   * keys, with associated sort parameters.
19   * Search results are sorted at the LDAP server according to the parameters 
20   * supplied in the sort control and then returned to the requestor. If sorting 
21   * is not supported at the server (and the sort control is marked as critical) 
22   * then the search operation is not performed and an error is returned.
23   * <p>
24   * The following code sample shows how the class may be used:
25   * <pre>
26   *
27   *     // Open an LDAP association
28   *     LdapContext ctx = new InitialLdapContext();
29   *
30   *     // Activate sorting
31   *     String sortKey = "cn";
32   *     ctx.setRequestControls(new Control[]{ 
33   *         new SortControl(sortKey, Control.CRITICAL) });
34   *
35   *     // Perform a search
36   *     NamingEnumeration results =
37   *         ctx.search("", "(objectclass=*)", new SearchControls());
38   *
39   *     // Iterate over search results
40   *     while (results != null && results.hasMore()) {
41   *         // Display an entry
42   *         SearchResult entry = (SearchResult)results.next();
43   *         System.out.println(entry.getName());
44   *         System.out.println(entry.getAttributes());
45   *
46   *         // Handle the entry's response controls (if any)
47   *         if (entry instanceof HasControls) {
48   *             // ((HasControls)entry).getControls();
49   *         }
50   *     }
51   *     // Examine the sort control response 
52   *     Control[] controls = ctx.getResponseControls();
53   *     if (controls != null) {
54   *         for (int i = 0; i < controls.length; i++) {
55   *             if (controls[i] instanceof SortResponseControl) {
56   *                 SortResponseControl src = (SortResponseControl)controls[i];
57   *                 if (! src.isSorted()) {
58   *                     throw src.getException();
59   *                 }
60   *             } else {
61   *                 // Handle other response controls (if any)
62   *             }
63   *         }
64   *     }
65   *
66   *     // Close the LDAP association
67   *     ctx.close();
68   *     ...
69   *
70   * </pre>
71   * <p>
72   * This class implements the LDAPv3 Request Control for server-side sorting
73   * as defined in
74   * <a HREF="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</a>.
75   *
76   * The control's value has the following ASN.1 definition:
77   * <pre>
78   *
79   *     SortKeyList ::= SEQUENCE OF SEQUENCE {
80   *         attributeType     AttributeDescription,
81   *         orderingRule  [0] MatchingRuleId OPTIONAL,
82   *         reverseOrder  [1] BOOLEAN DEFAULT FALSE }
83   *
84   * </pre>
85   *
86   * @since 1.5
87   * @see SortKey
88   * @see SortResponseControl
89   * @author Vincent Ryan
90   */
91  final public class SortControl extends BasicControl   {
92  
93      /**
94       * The server-side sort control's assigned object identifier
95       * is 1.2.840.113556.1.4.473.
96       */
97      public static final String   OID = "1.2.840.113556.1.4.473";
98  
99      private static final long serialVersionUID = -1965961680233330744L;
100 
101     /**
102      * Constructs a control to sort on a single attribute in ascending order.
103      * Sorting will be performed using the ordering matching rule defined 
104      * for use with the specified attribute.
105      *
106      * @param   sortBy  An attribute ID to sort by.
107      * @param   criticality     If true then the server must honor the control 
108      *                          and return the search results sorted as 
109      *                          requested or refuse to perform the search. 
110      *                          If false, then the server need not honor the 
111      *                          control.
112      * @exception IOException If an error was encountered while encoding the 
113      *                        supplied arguments into a control.
114      */
115     public SortControl(String   sortBy, boolean criticality) throws IOException   {
116 
117     super(OID, criticality, null);
118     super.value = setEncodedValue(new SortKey  []{ new SortKey  (sortBy) });
119     }
120 
121     /**
122      * Constructs a control to sort on a list of attributes in ascending order.
123      * Sorting will be performed using the ordering matching rule defined 
124      * for use with each of the specified attributes.
125      *
126      * @param   sortBy  A non-null list of attribute IDs to sort by.
127      *                  The list is in order of highest to lowest sort key
128      *                  precedence.
129      * @param   criticality     If true then the server must honor the control 
130      *                          and return the search results sorted as 
131      *                          requested or refuse to perform the search. 
132      *                          If false, then the server need not honor the 
133      *                          control.
134      * @exception IOException If an error was encountered while encoding the 
135      *                        supplied arguments into a control.
136      */
137     public SortControl(String  [] sortBy, boolean criticality)
138     throws IOException   {
139 
140     super(OID, criticality, null);
141     SortKey  [] sortKeys = new SortKey  [sortBy.length];
142     for (int i = 0; i < sortBy.length; i++) {
143         sortKeys[i] = new SortKey  (sortBy[i]);
144     }
145     super.value = setEncodedValue(sortKeys);
146     }
147 
148     /**
149      * Constructs a control to sort on a list of sort keys.
150      * Each sort key specifies the sort order and ordering matching rule to use.
151      *
152      * @param   sortBy      A non-null list of keys to sort by.
153      *                      The list is in order of highest to lowest sort key
154      *                      precedence.
155      * @param   criticality     If true then the server must honor the control 
156      *                          and return the search results sorted as 
157      *                          requested or refuse to perform the search. 
158      *                          If false, then the server need not honor the 
159      *                          control.
160      * @exception IOException If an error was encountered while encoding the 
161      *                        supplied arguments into a control.
162      */
163     public SortControl(SortKey  [] sortBy, boolean criticality)
164     throws IOException   {
165 
166     super(OID, criticality, null);
167     super.value = setEncodedValue(sortBy);
168     }
169 
170     /*
171      * Encodes the sort control's value using ASN.1 BER.
172      * The result includes the BER tag and length for the control's value but 
173      * does not include the control's object identifer and criticality setting.
174      *
175      * @param   sortKeys    A non-null list of keys to sort by.
176      * @return A possibly null byte array representing the ASN.1 BER encoded
177      *         value of the sort control.
178      * @exception IOException If a BER encoding error occurs.
179      */
180     private byte[] setEncodedValue(SortKey  [] sortKeys) throws IOException   {
181 
182     // build the ASN.1 BER encoding
183     BerEncoder ber = new BerEncoder(30 * sortKeys.length + 10);
184     String   matchingRule;
185 
186     ber.beginSeq(Ber.ASN_SEQUENCE | Ber.ASN_CONSTRUCTOR);
187 
188     for (int i = 0; i < sortKeys.length; i++) {
189         ber.beginSeq(Ber.ASN_SEQUENCE | Ber.ASN_CONSTRUCTOR);
190         ber.encodeString(sortKeys[i].getAttributeID(), true); // v3
191 
192         if ((matchingRule = sortKeys[i].getMatchingRuleID()) != null) {
193         ber.encodeString(matchingRule, (Ber.ASN_CONTEXT | 0), true);
194         }
195         if (! sortKeys[i].isAscending()) {
196         ber.encodeBoolean(true, (Ber.ASN_CONTEXT | 1));
197         }
198         ber.endSeq();
199     }
200     ber.endSeq();
201 
202     return ber.getTrimmedBuf();
203     }
204 }
205
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags