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 * }
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
|
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 * {@code LdapContext.extendedOperation()} 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 * }
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 * {@code ExtendedRequest.requestName} 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 {@code ExtendedRequest.requestValue}
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
|