1. /*
  2. * @(#)ExtendedRequest.java 1.9 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 javax.naming.NamingException;
  9. /**
  10. * This interface represents an LDAPv3 extended operation request as defined in
  11. * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC 2251</A>.
  12. * <pre>
  13. * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
  14. * requestName [0] LDAPOID,
  15. * requestValue [1] OCTET STRING OPTIONAL }
  16. * </pre>
  17. * It comprises an object identifier string and an optional ASN.1 BER
  18. * encoded value.
  19. *<p>
  20. * The methods in this class are used by the service provider to construct
  21. * the bits to send to the LDAP server. Applications typically only deal with
  22. * the classes that implement this interface, supplying them with
  23. * any information required for a particular extended operation request.
  24. * It would then pass such a class as an argument to the
  25. * <tt>LdapContext.extendedOperation()</tt> method for performing the
  26. * LDAPv3 extended operation.
  27. *<p>
  28. * For example, suppose the LDAP server supported a 'get time' extended operation.
  29. * It would supply GetTimeRequest and GetTimeResponse classes:
  30. *<blockquote><pre>
  31. * public class GetTimeRequest implements ExtendedRequest {
  32. * public GetTimeRequest() {... };
  33. * public ExtendedResponse createExtendedResponse(String id,
  34. * byte[] berValue, int offset, int length)
  35. * throws NamingException {
  36. * return new GetTimeResponse(id, berValue, offset, length);
  37. * }
  38. * ...
  39. * }
  40. * public class GetTimeResponse implements ExtendedResponse {
  41. * long time;
  42. * public GetTimeResponse(String id, byte[] berValue, int offset,
  43. * int length) throws NamingException {
  44. * time = ... // decode berValue to get time
  45. * }
  46. * public java.util.Date getDate() { return new java.util.Date(time) };
  47. * public long getTime() { return time };
  48. * ...
  49. * }
  50. *</pre></blockquote>
  51. * A program would use then these classes as follows:
  52. *<blockquote><pre>
  53. * GetTimeResponse resp =
  54. * (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
  55. * long time = resp.getTime();
  56. *</pre></blockquote>
  57. *
  58. * @author Rosanna Lee
  59. * @author Scott Seligman
  60. * @author Vincent Ryan
  61. * @version 1.9 03/12/19
  62. *
  63. * @see ExtendedResponse
  64. * @see LdapContext#extendedOperation
  65. * @since 1.3
  66. */
  67. public interface ExtendedRequest extends java.io.Serializable {
  68. /**
  69. * Retrieves the object identifier of the request.
  70. *
  71. * @return The non-null object identifier string representing the LDAP
  72. * <tt>ExtendedRequest.requestName</tt> component.
  73. */
  74. public String getID();
  75. /**
  76. * Retrieves the ASN.1 BER encoded value of the LDAP extended operation
  77. * request. Null is returned if the value is absent.
  78. *
  79. * The result is the raw BER bytes including the tag and length of
  80. * the request value. It does not include the request OID.
  81. * This method is called by the service provider to get the bits to
  82. * put into the extended operation to be sent to the LDAP server.
  83. *
  84. * @return A possibly null byte array representing the ASN.1 BER encoded
  85. * contents of the LDAP <tt>ExtendedRequest.requestValue</tt>
  86. * component.
  87. * @exception IllegalStateException If the encoded value cannot be retrieved
  88. * because the request contains insufficient or invalid data/state.
  89. */
  90. public byte[] getEncodedValue();
  91. /**
  92. * Creates the response object that corresponds to this request.
  93. *<p>
  94. * After the service provider has sent the extended operation request
  95. * to the LDAP server, it will receive a response from the server.
  96. * If the operation failed, the provider will throw a NamingException.
  97. * If the operation succeeded, the provider will invoke this method
  98. * using the data that it got back in the response.
  99. * It is the job of this method to return a class that implements
  100. * the ExtendedResponse interface that is appropriate for the
  101. * extended operation request.
  102. *<p>
  103. * For example, a Start TLS extended request class would need to know
  104. * how to process a Start TLS extended response. It does this by creating
  105. * a class that implements ExtendedResponse.
  106. *
  107. * @param id The possibly null object identifier of the response
  108. * control.
  109. * @param berValue The possibly null ASN.1 BER encoded value of the
  110. * response control.
  111. * This is the raw BER bytes including the tag and length of
  112. * the response value. It does not include the response OID.
  113. * @param offset The starting position in berValue of the bytes to use.
  114. * @param length The number of bytes in berValue to use.
  115. *
  116. * @return A non-null object.
  117. * @exception NamingException if cannot create extended response
  118. * due to an error.
  119. * @see ExtendedResponse
  120. */
  121. public ExtendedResponse createExtendedResponse(String id,
  122. byte[] berValue, int offset, int length) throws NamingException;
  123. // static final long serialVersionUID = -7560110759229059814L;
  124. }