001 /*
002 * Copyright 2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.ldap;
027
028 import java.io.IOException;
029 import com.sun.jndi.ldap.Ber;
030 import com.sun.jndi.ldap.BerEncoder;
031
032 /**
033 * Requests that the results of a search operation be returned by the LDAP
034 * server in batches of a specified size.
035 * The requestor controls the rate at which batches are returned by the rate
036 * at which it invokes search operations.
037 * <p>
038 * The following code sample shows how the class may be used:
039 * <pre>
040 *
041 * // Open an LDAP association
042 * LdapContext ctx = new InitialLdapContext();
043 *
044 * // Activate paged results
045 * int pageSize = 20; // 20 entries per page
046 * byte[] cookie = null;
047 * int total;
048 * ctx.setRequestControls(new Control[]{
049 * new PagedResultsControl(pageSize, Control.CRITICAL) });
050 *
051 * do {
052 * // Perform the search
053 * NamingEnumeration results =
054 * ctx.search("", "(objectclass=*)", new SearchControls());
055 *
056 * // Iterate over a batch of search results
057 * while (results != null && results.hasMore()) {
058 * // Display an entry
059 * SearchResult entry = (SearchResult)results.next();
060 * System.out.println(entry.getName());
061 * System.out.println(entry.getAttributes());
062 *
063 * // Handle the entry's response controls (if any)
064 * if (entry instanceof HasControls) {
065 * // ((HasControls)entry).getControls();
066 * }
067 * }
068 * // Examine the paged results control response
069 * Control[] controls = ctx.getResponseControls();
070 * if (controls != null) {
071 * for (int i = 0; i < controls.length; i++) {
072 * if (controls[i] instanceof PagedResultsResponseControl) {
073 * PagedResultsResponseControl prrc =
074 * (PagedResultsResponseControl)controls[i];
075 * total = prrc.getResultSize();
076 * cookie = prrc.getCookie();
077 * } else {
078 * // Handle other response controls (if any)
079 * }
080 * }
081 * }
082 *
083 * // Re-activate paged results
084 * ctx.setRequestControls(new Control[]{
085 * new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
086 * } while (cookie != null);
087 *
088 * // Close the LDAP association
089 * ctx.close();
090 * ...
091 *
092 * </pre>
093 * <p>
094 * This class implements the LDAPv3 Control for paged-results as defined in
095 * <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>.
096 *
097 * The control's value has the following ASN.1 definition:
098 * <pre>
099 *
100 * realSearchControlValue ::= SEQUENCE {
101 * size INTEGER (0..maxInt),
102 * -- requested page size from client
103 * -- result set size estimate from server
104 * cookie OCTET STRING
105 * }
106 *
107 * </pre>
108 *
109 * @since 1.5
110 * @see PagedResultsResponseControl
111 * @author Vincent Ryan
112 */
113 final public class PagedResultsControl extends BasicControl {
114
115 /**
116 * The paged-results control's assigned object identifier
117 * is 1.2.840.113556.1.4.319.
118 */
119 public static final String OID = "1.2.840.113556.1.4.319";
120
121 private static final byte[] EMPTY_COOKIE = new byte[0];
122
123 private static final long serialVersionUID = 6684806685736844298L;
124
125 /**
126 * Constructs a control to set the number of entries to be returned per
127 * page of results.
128 *
129 * @param pageSize The number of entries to return in a page.
130 * @param criticality If true then the server must honor the control
131 * and return search results as indicated by
132 * pageSize or refuse to perform the search.
133 * If false, then the server need not honor the
134 * control.
135 * @exception IOException If an error was encountered while encoding the
136 * supplied arguments into a control.
137 */
138 public PagedResultsControl(int pageSize, boolean criticality)
139 throws IOException {
140
141 super (OID, criticality, null);
142 value = setEncodedValue(pageSize, EMPTY_COOKIE);
143 }
144
145 /**
146 * Constructs a control to set the number of entries to be returned per
147 * page of results. The cookie is provided by the server and may be
148 * obtained from the paged-results response control.
149 * <p>
150 * A sequence of paged-results can be abandoned by setting the pageSize
151 * to zero and setting the cookie to the last cookie received from the
152 * server.
153 *
154 * @param pageSize The number of entries to return in a page.
155 * @param cookie A possibly null server-generated cookie.
156 * @param criticality If true then the server must honor the control
157 * and return search results as indicated by
158 * pageSize or refuse to perform the search.
159 * If false, then the server need not honor the
160 * control.
161 * @exception IOException If an error was encountered while encoding the
162 * supplied arguments into a control.
163 */
164 public PagedResultsControl(int pageSize, byte[] cookie,
165 boolean criticality) throws IOException {
166
167 super (OID, criticality, null);
168 if (cookie == null) {
169 cookie = EMPTY_COOKIE;
170 }
171 value = setEncodedValue(pageSize, cookie);
172 }
173
174 /*
175 * Encodes the paged-results control's value using ASN.1 BER.
176 * The result includes the BER tag and length for the control's value but
177 * does not include the control's object identifier and criticality setting.
178 *
179 * @param pageSize The number of entries to return in a page.
180 * @param cookie A non-null server-generated cookie.
181 * @return A possibly null byte array representing the ASN.1 BER encoded
182 * value of the LDAP paged-results control.
183 * @exception IOException If a BER encoding error occurs.
184 */
185 private byte[] setEncodedValue(int pageSize, byte[] cookie)
186 throws IOException {
187
188 // build the ASN.1 encoding
189 BerEncoder ber = new BerEncoder(10 + cookie.length);
190
191 ber.beginSeq(Ber.ASN_SEQUENCE | Ber.ASN_CONSTRUCTOR);
192 ber.encodeInt(pageSize);
193 ber.encodeOctetString(cookie, Ber.ASN_OCTET_STR);
194 ber.endSeq();
195
196 return ber.getTrimmedBuf();
197 }
198 }
|