001 /*
002 * Copyright 1999-2000 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.ldap;
027
028 import javax.naming.NamingException;
029
030 /**
031 * This interface represents an LDAPv3 extended operation request as defined in
032 * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC 2251</A>.
033 * <pre>
034 * ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
035 * requestName [0] LDAPOID,
036 * requestValue [1] OCTET STRING OPTIONAL }
037 * </pre>
038 * It comprises an object identifier string and an optional ASN.1 BER
039 * encoded value.
040 *<p>
041 * The methods in this class are used by the service provider to construct
042 * the bits to send to the LDAP server. Applications typically only deal with
043 * the classes that implement this interface, supplying them with
044 * any information required for a particular extended operation request.
045 * It would then pass such a class as an argument to the
046 * <tt>LdapContext.extendedOperation()</tt> method for performing the
047 * LDAPv3 extended operation.
048 *<p>
049 * For example, suppose the LDAP server supported a 'get time' extended operation.
050 * It would supply GetTimeRequest and GetTimeResponse classes:
051 *<blockquote><pre>
052 * public class GetTimeRequest implements ExtendedRequest {
053 * public GetTimeRequest() {... };
054 * public ExtendedResponse createExtendedResponse(String id,
055 * byte[] berValue, int offset, int length)
056 * throws NamingException {
057 * return new GetTimeResponse(id, berValue, offset, length);
058 * }
059 * ...
060 * }
061 * public class GetTimeResponse implements ExtendedResponse {
062 * long time;
063 * public GetTimeResponse(String id, byte[] berValue, int offset,
064 * int length) throws NamingException {
065 * time = ... // decode berValue to get time
066 * }
067 * public java.util.Date getDate() { return new java.util.Date(time) };
068 * public long getTime() { return time };
069 * ...
070 * }
071 *</pre></blockquote>
072 * A program would use then these classes as follows:
073 *<blockquote><pre>
074 * GetTimeResponse resp =
075 * (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
076 * long time = resp.getTime();
077 *</pre></blockquote>
078 *
079 * @author Rosanna Lee
080 * @author Scott Seligman
081 * @author Vincent Ryan
082 * @version 1.16 07/05/05
083 *
084 * @see ExtendedResponse
085 * @see LdapContext#extendedOperation
086 * @since 1.3
087 */
088 public interface ExtendedRequest extends java.io.Serializable {
089
090 /**
091 * Retrieves the object identifier of the request.
092 *
093 * @return The non-null object identifier string representing the LDAP
094 * <tt>ExtendedRequest.requestName</tt> component.
095 */
096 public String getID();
097
098 /**
099 * Retrieves the ASN.1 BER encoded value of the LDAP extended operation
100 * request. Null is returned if the value is absent.
101 *
102 * The result is the raw BER bytes including the tag and length of
103 * the request value. It does not include the request OID.
104 * This method is called by the service provider to get the bits to
105 * put into the extended operation to be sent to the LDAP server.
106 *
107 * @return A possibly null byte array representing the ASN.1 BER encoded
108 * contents of the LDAP <tt>ExtendedRequest.requestValue</tt>
109 * component.
110 * @exception IllegalStateException If the encoded value cannot be retrieved
111 * because the request contains insufficient or invalid data/state.
112 */
113 public byte[] getEncodedValue();
114
115 /**
116 * Creates the response object that corresponds to this request.
117 *<p>
118 * After the service provider has sent the extended operation request
119 * to the LDAP server, it will receive a response from the server.
120 * If the operation failed, the provider will throw a NamingException.
121 * If the operation succeeded, the provider will invoke this method
122 * using the data that it got back in the response.
123 * It is the job of this method to return a class that implements
124 * the ExtendedResponse interface that is appropriate for the
125 * extended operation request.
126 *<p>
127 * For example, a Start TLS extended request class would need to know
128 * how to process a Start TLS extended response. It does this by creating
129 * a class that implements ExtendedResponse.
130 *
131 * @param id The possibly null object identifier of the response
132 * control.
133 * @param berValue The possibly null ASN.1 BER encoded value of the
134 * response control.
135 * This is the raw BER bytes including the tag and length of
136 * the response value. It does not include the response OID.
137 * @param offset The starting position in berValue of the bytes to use.
138 * @param length The number of bytes in berValue to use.
139 *
140 * @return A non-null object.
141 * @exception NamingException if cannot create extended response
142 * due to an error.
143 * @see ExtendedResponse
144 */
145 public ExtendedResponse createExtendedResponse(String id,
146 byte[] berValue, int offset, int length)
147 throws NamingException;
148
149 // static final long serialVersionUID = -7560110759229059814L;
150 }
|