KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > ldap > ExtendedRequest


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