1 /* 2 * Copyright 1999-2000 Sun Microsystems, Inc. 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. Sun designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 22 * CA 95054 USA or visit www.sun.com if you need additional information or 23 * have any 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 }