Back to index...

	/*
	* 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();
	}
	}

Back to index...