1/* 2 * Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.naming.ldap; 27 28import java.io.IOException; 29import com.sun.jndi.ldap.Ber; 30import com.sun.jndi.ldap.BerDecoder; 31 32/** 33 * Indicates the end of a batch of search results. 34 * Contains an estimate of the total number of entries in the result set 35 * and an opaque cookie. The cookie must be supplied to the next search 36 * operation in order to get the next batch of results. 37 * <p> 38 * The code sample in {@link PagedResultsControl} shows how this class may 39 * be used. 40 * <p> 41 * This class implements the LDAPv3 Response Control for 42 * paged-results as defined in 43 * <a href="http://www.ietf.org/rfc/rfc2696">RFC 2696</a>. 44 * 45 * The control's value has the following ASN.1 definition: 46 * <pre> 47 * 48 * realSearchControlValue ::= SEQUENCE { 49 * size INTEGER (0..maxInt), 50 * -- requested page size from client 51 * -- result set size estimate from server 52 * cookie OCTET STRING 53 * } 54 * 55 * </pre> 56 * 57 * @since 1.5 58 * @see PagedResultsControl 59 * @author Vincent Ryan 60 */ 61final public class PagedResultsResponseControl extends BasicControl { 62 63 /** 64 * The paged-results response control's assigned object identifier 65 * is 1.2.840.113556.1.4.319. 66 */ 67 public static final String OID = "1.2.840.113556.1.4.319"; 68 69 private static final long serialVersionUID = -8819778744844514666L; 70 71 /** 72 * An estimate of the number of entries in the search result. 73 * 74 * @serial 75 */ 76 private int resultSize; 77 78 /** 79 * A server-generated cookie. 80 * 81 * @serial 82 */ 83 private byte[] cookie; 84 85 /** 86 * Constructs a paged-results response control. 87 * 88 * @param id The control's object identifier string. 89 * @param criticality The control's criticality. 90 * @param value The control's ASN.1 BER encoded value. 91 * It is not cloned - any changes to value 92 * will affect the contents of the control. 93 * @exception IOException If an error was encountered while decoding 94 * the control's value. 95 */ 96 public PagedResultsResponseControl(String id, boolean criticality, 97 byte[] value) throws IOException { 98 99 super(id, criticality, value); 100 101 // decode value 102 BerDecoder ber = new BerDecoder(value, 0, value.length); 103 104 ber.parseSeq(null); 105 resultSize = ber.parseInt(); 106 cookie = ber.parseOctetString(Ber.ASN_OCTET_STR, null); 107 } 108 109 /** 110 * Retrieves (an estimate of) the number of entries in the search result. 111 * 112 * @return The number of entries in the search result, or zero if unknown. 113 */ 114 public int getResultSize() { 115 return resultSize; 116 } 117 118 /** 119 * Retrieves the server-generated cookie. Null is returned when there are 120 * no more entries for the server to return. 121 * 122 * @return A possibly null server-generated cookie. It is not cloned - any 123 * changes to the cookie will update the control's state and thus 124 * are not recommended. 125 */ 126 public byte[] getCookie() { 127 if (cookie.length == 0) { 128 return null; 129 } else { 130 return cookie; 131 } 132 } 133} 134