1. /*
  2. * @(#)PagedResultsResponseControl.java 1.3 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. package javax.naming.ldap;
  8. import java.io.IOException;
  9. import com.sun.jndi.ldap.Ber;
  10. import com.sun.jndi.ldap.BerDecoder;
  11. /**
  12. * Indicates the end of a batch of search results.
  13. * Contains an estimate of the total number of entries in the result set
  14. * and an opaque cookie. The cookie must be supplied to the next search
  15. * operation in order to get the next batch of results.
  16. * <p>
  17. * The code sample in {@link PagedResultsControl} shows how this class may
  18. * be used.
  19. * <p>
  20. * This class implements the LDAPv3 Response Control for
  21. * paged-results as defined in
  22. * <a href="http://www.ietf.org/rfc/rfc2696">RFC 2696</a>.
  23. *
  24. * The control's value has the following ASN.1 definition:
  25. * <pre>
  26. *
  27. * realSearchControlValue ::= SEQUENCE {
  28. * size INTEGER (0..maxInt),
  29. * -- requested page size from client
  30. * -- result set size estimate from server
  31. * cookie OCTET STRING
  32. * }
  33. *
  34. * </pre>
  35. *
  36. * @since 1.5
  37. * @see PagedResultsControl
  38. * @author Vincent Ryan
  39. */
  40. final public class PagedResultsResponseControl extends BasicControl {
  41. /**
  42. * The paged-results response control's assigned object identifier
  43. * is 1.2.840.113556.1.4.319.
  44. */
  45. public static final String OID = "1.2.840.113556.1.4.319";
  46. private static final long serialVersionUID = -8819778744844514666L;
  47. /**
  48. * An estimate of the number of entries in the search result.
  49. *
  50. * @serial
  51. */
  52. private int resultSize;
  53. /**
  54. * A server-generated cookie.
  55. *
  56. * @serial
  57. */
  58. private byte[] cookie;
  59. /**
  60. * Constructs a paged-results response control.
  61. *
  62. * @param id The control's object identifier string.
  63. * @param criticality The control's criticality.
  64. * @param value The control's ASN.1 BER encoded value.
  65. * It is not cloned - any changes to value
  66. * will affect the contents of the control.
  67. * @exception IOException If an error was encountered while decoding
  68. * the control's value.
  69. */
  70. public PagedResultsResponseControl(String id, boolean criticality,
  71. byte[] value) throws IOException {
  72. super(id, criticality, value);
  73. // decode value
  74. BerDecoder ber = new BerDecoder(value, 0, value.length);
  75. ber.parseSeq(null);
  76. resultSize = ber.parseInt();
  77. cookie = ber.parseOctetString(Ber.ASN_OCTET_STR, null);
  78. }
  79. /**
  80. * Retrieves (an estimate of) the number of entries in the search result.
  81. *
  82. * @return The number of entries in the search result, or zero if unknown.
  83. */
  84. public int getResultSize() {
  85. return resultSize;
  86. }
  87. /**
  88. * Retrieves the server-generated cookie. Null is returned when there are
  89. * no more entries for the server to return.
  90. *
  91. * @return A possibly null server-generated cookie. It is not cloned - any
  92. * changes to the cookie will update the control's state and thus
  93. * are not recommended.
  94. */
  95. public byte[] getCookie() {
  96. if (cookie.length == 0) {
  97. return null;
  98. } else {
  99. return cookie;
  100. }
  101. }
  102. }