View Javadoc
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  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 }