Java tutorial
/* * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.naming.ldap; import java.io.IOException; import com.sun.jndi.ldap.Ber; import com.sun.jndi.ldap.BerEncoder; /** * Requests that the results of a search operation be returned by the LDAP * server in batches of a specified size. * The requestor controls the rate at which batches are returned by the rate * at which it invokes search operations. * <p> * The following code sample shows how the class may be used: * <pre>{@code * * // Open an LDAP association * LdapContext ctx = new InitialLdapContext(); * * // Activate paged results * int pageSize = 20; // 20 entries per page * byte[] cookie = null; * int total; * ctx.setRequestControls(new Control[]{ * new PagedResultsControl(pageSize, Control.CRITICAL) }); * * do { * // Perform the search * NamingEnumeration results = * ctx.search("", "(objectclass=*)", new SearchControls()); * * // Iterate over a batch of search results * while (results != null && results.hasMore()) { * // Display an entry * SearchResult entry = (SearchResult)results.next(); * System.out.println(entry.getName()); * System.out.println(entry.getAttributes()); * * // Handle the entry's response controls (if any) * if (entry instanceof HasControls) { * // ((HasControls)entry).getControls(); * } * } * // Examine the paged results control response * Control[] controls = ctx.getResponseControls(); * if (controls != null) { * for (int i = 0; i < controls.length; i++) { * if (controls[i] instanceof PagedResultsResponseControl) { * PagedResultsResponseControl prrc = * (PagedResultsResponseControl)controls[i]; * total = prrc.getResultSize(); * cookie = prrc.getCookie(); * } else { * // Handle other response controls (if any) * } * } * } * * // Re-activate paged results * ctx.setRequestControls(new Control[]{ * new PagedResultsControl(pageSize, cookie, Control.CRITICAL) }); * } while (cookie != null); * * // Close the LDAP association * ctx.close(); * ... * * } </pre> * <p> * This class implements the LDAPv3 Control for paged-results as defined in * <a href="http://www.ietf.org/rfc/rfc2696.txt">RFC 2696</a>. * * The control's value has the following ASN.1 definition: * <pre>{@code * * realSearchControlValue ::= SEQUENCE { * size INTEGER (0..maxInt), * -- requested page size from client * -- result set size estimate from server * cookie OCTET STRING * } * * }</pre> * * @since 1.5 * @see PagedResultsResponseControl * @author Vincent Ryan */ final public class PagedResultsControl extends BasicControl { /** * The paged-results control's assigned object identifier * is 1.2.840.113556.1.4.319. */ public static final String OID = "1.2.840.113556.1.4.319"; private static final byte[] EMPTY_COOKIE = new byte[0]; private static final long serialVersionUID = 6684806685736844298L; /** * Constructs a control to set the number of entries to be returned per * page of results. * * @param pageSize The number of entries to return in a page. * @param criticality If true then the server must honor the control * and return search results as indicated by * pageSize or refuse to perform the search. * If false, then the server need not honor the * control. * @exception IOException If an error was encountered while encoding the * supplied arguments into a control. */ public PagedResultsControl(int pageSize, boolean criticality) throws IOException { super(OID, criticality, null); value = setEncodedValue(pageSize, EMPTY_COOKIE); } /** * Constructs a control to set the number of entries to be returned per * page of results. The cookie is provided by the server and may be * obtained from the paged-results response control. * <p> * A sequence of paged-results can be abandoned by setting the pageSize * to zero and setting the cookie to the last cookie received from the * server. * * @param pageSize The number of entries to return in a page. * @param cookie A possibly null server-generated cookie. * @param criticality If true then the server must honor the control * and return search results as indicated by * pageSize or refuse to perform the search. * If false, then the server need not honor the * control. * @exception IOException If an error was encountered while encoding the * supplied arguments into a control. */ public PagedResultsControl(int pageSize, byte[] cookie, boolean criticality) throws IOException { super(OID, criticality, null); if (cookie == null) { cookie = EMPTY_COOKIE; } value = setEncodedValue(pageSize, cookie); } /* * Encodes the paged-results control's value using ASN.1 BER. * The result includes the BER tag and length for the control's value but * does not include the control's object identifier and criticality setting. * * @param pageSize The number of entries to return in a page. * @param cookie A non-null server-generated cookie. * @return A possibly null byte array representing the ASN.1 BER encoded * value of the LDAP paged-results control. * @exception IOException If a BER encoding error occurs. */ private byte[] setEncodedValue(int pageSize, byte[] cookie) throws IOException { // build the ASN.1 encoding BerEncoder ber = new BerEncoder(10 + cookie.length); ber.beginSeq(Ber.ASN_SEQUENCE | Ber.ASN_CONSTRUCTOR); ber.encodeInt(pageSize); ber.encodeOctetString(cookie, Ber.ASN_OCTET_STR); ber.endSeq(); return ber.getTrimmedBuf(); } }