KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > ldap > PagedResultsControl


1 /*
2  * @(#)PagedResultsControl.java 1.4 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 JavaDoc;
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 returned by the LDAP
16  * server in batches of a specified size.
17  * The requestor controls the rate at which batches are returned by the rate
18  * at which it invokes search operations.
19  * <p>
20  * The following code sample shows how the class may be used:
21  * <pre>
22  *
23  * // Open an LDAP association
24  * LdapContext ctx = new InitialLdapContext();
25  *
26  * // Activate paged results
27  * int pageSize = 20; // 20 entries per page
28  * byte[] cookie = null;
29  * int total;
30  * ctx.setRequestControls(new Control[]{
31  * new PagedResultsControl(pageSize, Control.CRITICAL) });
32  *
33  * do {
34  * // Perform the search
35  * NamingEnumeration results =
36  * ctx.search("", "(objectclass=*)", new SearchControls());
37  *
38  * // Iterate over a batch of search results
39  * while (results != null && results.hasMore()) {
40  * // Display an entry
41  * SearchResult entry = (SearchResult)results.next();
42  * System.out.println(entry.getName());
43  * System.out.println(entry.getAttributes());
44  *
45  * // Handle the entry's response controls (if any)
46  * if (entry instanceof HasControls) {
47  * // ((HasControls)entry).getControls();
48  * }
49  * }
50  * // Examine the paged results control response
51  * Control[] controls = ctx.getResponseControls();
52  * if (controls != null) {
53  * for (int i = 0; i < controls.length; i++) {
54  * if (controls[i] instanceof PagedResultsResponseControl) {
55  * PagedResultsResponseControl prrc =
56  * (PagedResultsResponseControl)controls[i];
57  * total = prrc.getResultSize();
58  * cookie = prrc.getCookie();
59  * } else {
60  * // Handle other response controls (if any)
61  * }
62  * }
63  * }
64  *
65  * // Re-activate paged results
66  * ctx.setRequestControls(new Control[]{
67  * new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
68  * } while (cookie != null);
69  *
70  * // Close the LDAP association
71  * ctx.close();
72  * ...
73  *
74  * </pre>
75  * <p>
76  * This class implements the LDAPv3 Control for paged-results as defined in
77  * <a HREF="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
78  *
79  * The control's value has the following ASN.1 definition:
80  * <pre>
81  *
82  * realSearchControlValue ::= SEQUENCE {
83  * size INTEGER (0..maxInt),
84  * -- requested page size from client
85  * -- result set size estimate from server
86  * cookie OCTET STRING
87  * }
88  *
89  * </pre>
90  *
91  * @since 1.5
92  * @see PagedResultsResponseControl
93  * @author Vincent Ryan
94  */
95 final public class PagedResultsControl extends BasicControl JavaDoc {
96
97     /**
98      * The paged-results control's assigned object identifier
99      * is 1.2.840.113556.1.4.319.
100      */
101     public static final String JavaDoc OID = "1.2.840.113556.1.4.319";
102
103     private static final byte[] EMPTY_COOKIE = new byte[0];
104
105     private static final long serialVersionUID = 6684806685736844298L;
106
107     /**
108      * Constructs a control to set the number of entries to be returned per
109      * page of results.
110      *
111      * @param pageSize The number of entries to return in a page.
112      * @param criticality If true then the server must honor the control
113      * and return search results as indicated by
114      * pageSize or refuse to perform the search.
115      * If false, then the server need not honor the
116      * control.
117      * @exception IOException If an error was encountered while encoding the
118      * supplied arguments into a control.
119      */
120     public PagedResultsControl(int pageSize, boolean criticality)
121         throws IOException JavaDoc {
122
123     super(OID, criticality, null);
124     value = setEncodedValue(pageSize, EMPTY_COOKIE);
125     }
126
127     /**
128      * Constructs a control to set the number of entries to be returned per
129      * page of results. The cookie is provided by the server and may be
130      * obtained from the paged-results response control.
131      * <p>
132      * A sequence of paged-results can be abandoned by setting the pageSize
133      * to zero and setting the cookie to the last cookie received from the
134      * server.
135      *
136      * @param pageSize The number of entries to return in a page.
137      * @param cookie A possibly null server-generated cookie.
138      * @param criticality If true then the server must honor the control
139      * and return search results as indicated by
140      * pageSize or refuse to perform the search.
141      * If false, then the server need not honor the
142      * control.
143      * @exception IOException If an error was encountered while encoding the
144      * supplied arguments into a control.
145      */
146     public PagedResultsControl(int pageSize, byte[] cookie,
147     boolean criticality) throws IOException JavaDoc {
148
149     super(OID, criticality, null);
150     if (cookie == null) {
151         cookie = EMPTY_COOKIE;
152     }
153     value = setEncodedValue(pageSize, cookie);
154     }
155
156     /*
157      * Encodes the paged-results control's value using ASN.1 BER.
158      * The result includes the BER tag and length for the control's value but
159      * does not include the control's object identifier and criticality setting.
160      *
161      * @param pageSize The number of entries to return in a page.
162      * @param cookie A non-null server-generated cookie.
163      * @return A possibly null byte array representing the ASN.1 BER encoded
164      * value of the LDAP paged-results control.
165      * @exception IOException If a BER encoding error occurs.
166      */
167     private byte[] setEncodedValue(int pageSize, byte[] cookie)
168     throws IOException JavaDoc {
169
170     // build the ASN.1 encoding
171 BerEncoder ber = new BerEncoder(10 + cookie.length);
172
173     ber.beginSeq(Ber.ASN_SEQUENCE | Ber.ASN_CONSTRUCTOR);
174         ber.encodeInt(pageSize);
175             ber.encodeOctetString(cookie, Ber.ASN_OCTET_STR);
176     ber.endSeq();
177
178     return ber.getTrimmedBuf();
179     }
180 }
181
Popular Tags