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