1 /*
   2  * Copyright (c) 1999, 2010, 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 
  26 package javax.naming.ldap;
  27 
  28 /**
  29   * This interface represents an LDAP extended operation response as defined in
  30   * <A HREF="http://www.ietf.org/rfc/rfc2251.txt">RFC 2251</A>.
  31   * <pre>
  32   *     ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
  33   *          COMPONENTS OF LDAPResult,
  34   *          responseName     [10] LDAPOID OPTIONAL,
  35   *          response         [11] OCTET STRING OPTIONAL }
  36   * </pre>
  37   * It comprises an optional object identifier and an optional ASN.1 BER
  38   * encoded value.
  39   *
  40   *<p>
  41   * The methods in this class can be used by the application to get low
  42   * level information about the extended operation response. However, typically,
  43   * the application will be using methods specific to the class that
  44   * implements this interface. Such a class should have decoded the BER buffer
  45   * in the response and should provide methods that allow the user to
  46   * access that data in the response in a type-safe and friendly manner.
  47   *<p>
  48   * For example, suppose the LDAP server supported a 'get time' extended operation.
  49   * It would supply GetTimeRequest and GetTimeResponse classes.
  50   * The GetTimeResponse class might look like:
  51   *<blockquote><pre>
  52   * public class GetTimeResponse implements ExtendedResponse {
  53   *     public java.util.Date getDate() {...};
  54   *     public long getTime() {...};
  55   *     ....
  56   * }
  57   *</pre></blockquote>
  58   * A program would use then these classes as follows:
  59   *<blockquote><pre>
  60   * GetTimeResponse resp =
  61   *     (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
  62   * java.util.Date now = resp.getDate();
  63   *</pre></blockquote>
  64   *
  65   * @author Rosanna Lee
  66   * @author Scott Seligman
  67   * @author Vincent Ryan
  68   *
  69   * @see ExtendedRequest
  70   * @since 1.3
  71   */
  72 
  73 public interface ExtendedResponse extends java.io.Serializable {
  74 
  75     /**
  76       * Retrieves the object identifier of the response.
  77       * The LDAP protocol specifies that the response object identifier is optional.
  78       * If the server does not send it, the response will contain no ID (i.e. null).
  79       *
  80       * @return A possibly null object identifier string representing the LDAP
  81       *         <tt>ExtendedResponse.responseName</tt> component.
  82       */
  83     public String getID();
  84 
  85     /**
  86       * Retrieves the ASN.1 BER encoded value of the LDAP extended operation
  87       * response. Null is returned if the value is absent from the response
  88       * sent by the LDAP server.
  89       * The result is the raw BER bytes including the tag and length of
  90       * the response value. It does not include the response OID.
  91       *
  92       * @return A possibly null byte array representing the ASN.1 BER encoded
  93       *         contents of the LDAP <tt>ExtendedResponse.response</tt>
  94       *         component.
  95       */
  96     public byte[] getEncodedValue();
  97 
  98     //static final long serialVersionUID = -3320509678029180273L;
  99 }