| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <!-- |
| 5 | Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 8 | This code is free software; you can redistribute it and/or modify it |
| 9 | under the terms of the GNU General Public License version 2 only, as |
| 10 | published by the Free Software Foundation. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 14 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 15 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 16 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 17 | version 2 for more details (a copy is included in the LICENSE file that |
| 18 | accompanied this code). |
| 19 | |
| 20 | You should have received a copy of the GNU General Public License version |
| 21 | 2 along with this work; if not, write to the Free Software Foundation, |
| 22 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 27 | |
| 28 | --> |
| 29 | </head> |
| 30 | <body bgcolor="white"> |
| 31 | |
| 32 | Provides support for LDAPv3 extended operations and controls. |
| 33 | |
| 34 | <p> |
| 35 | This package extends the directory operations of the Java Naming and |
| 36 | Directory Interface<font size=-2><sup>TM</sup></font> (JNDI). |
| 37 | JNDI provides naming and directory functionality to applications |
| 38 | written in the Java programming language. It is designed to be |
| 39 | independent of any specific naming or directory service |
| 40 | implementation. Thus a variety of services--new, emerging, and |
| 41 | already deployed ones--can be accessed in a common way. |
| 42 | |
| 43 | <p> |
| 44 | This package is for applications and service providers that deal with |
| 45 | LDAPv3 extended operations and controls, as defined by |
| 46 | <a href=http://www.ietf.org/rfc/rfc2251.txt>RFC 2251</a>. |
| 47 | The core interface in this package is <tt>LdapContext</tt>, which defines |
| 48 | methods on a context for performing extended operations and handling |
| 49 | controls. |
| 50 | |
| 51 | <h4>Extended Operations</h4> |
| 52 | <p> |
| 53 | This package defines the interface <tt>ExtendedRequest</tt> |
| 54 | to represent the argument to an extended operation, |
| 55 | and the interface <tt>ExtendedResponse</tt> to represent the result |
| 56 | of the extended operation. |
| 57 | An extended response is always paired with an extended request |
| 58 | but not necessarily vice versa. That is, you can have an extended request |
| 59 | that has no corresponding extended response. |
| 60 | <p> |
| 61 | An application typically does not deal directly with these interfaces. |
| 62 | Instead, it deals with classes that <em>implement</em> these |
| 63 | interfaces. |
| 64 | The application gets these classes either as part of a |
| 65 | repertoire of extended operations standardized through the IETF, or |
| 66 | from directory vendors for vendor-specific extended operations. |
| 67 | The request classes should have constructors that accept |
| 68 | arguments in a type-safe and user-friendly manner, while the |
| 69 | response classes should have access methods for getting the data |
| 70 | of the response in a type-safe and user-friendly manner. |
| 71 | Internally, the request/response classes deal with encoding and decoding |
| 72 | BER values. |
| 73 | <p> |
| 74 | For example, suppose an LDAP server supports a "get time" extended operation. |
| 75 | It would supply classes such as |
| 76 | <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt>, |
| 77 | so that applications can use this feature. |
| 78 | An application would use these classes as follows: |
| 79 | <blockquote><pre> |
| 80 | GetTimeResponse resp = |
| 81 | (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest()); |
| 82 | long time = resp.getTime(); |
| 83 | </pre></blockquote> |
| 84 | <p> |
| 85 | The <tt>GetTimeRequest</tt> and <tt>GetTimeResponse</tt> classes might |
| 86 | be defined as follows: |
| 87 | <blockquote><pre> |
| 88 | public class GetTimeRequest implements ExtendedRequest { |
| 89 | // User-friendly constructor |
| 90 | public GetTimeRequest() { |
| 91 | }; |
| 92 | |
| 93 | // Methods used by service providers |
| 94 | public String getID() { |
| 95 | return GETTIME_REQ_OID; |
| 96 | } |
| 97 | public byte[] getEncodedValue() { |
| 98 | return null; // no value needed for get time request |
| 99 | } |
| 100 | public ExtendedResponse createExtendedResponse( |
| 101 | String id, byte[] berValue, int offset, int length) throws NamingException { |
| 102 | return new GetTimeResponse(id, berValue, offset, length); |
| 103 | } |
| 104 | } |
| 105 | public class GetTimeResponse() implements ExtendedResponse { |
| 106 | long time; |
| 107 | // called by GetTimeRequest.createExtendedResponse() |
| 108 | public GetTimeResponse(String id, byte[] berValue, int offset, int length) |
| 109 | throws NamingException { |
| 110 | // check validity of id |
| 111 | long time = ... // decode berValue to get time |
| 112 | } |
| 113 | |
| 114 | // Type-safe and User-friendly methods |
| 115 | public java.util.Date getDate() { return new java.util.Date(time); } |
| 116 | public long getTime() { return time; } |
| 117 | |
| 118 | // Low level methods |
| 119 | public byte[] getEncodedValue() { |
| 120 | return // berValue saved; |
| 121 | } |
| 122 | public String getID() { |
| 123 | return GETTIME_RESP_OID; |
| 124 | } |
| 125 | } |
| 126 | </pre></blockquote> |
| 127 | |
| 128 | <h4>Controls</h4> |
| 129 | |
| 130 | This package defines the interface <tt>Control</tt> to represent an LDAPv3 |
| 131 | control. It can be a control that is sent to an LDAP server |
| 132 | (<em>request control</em>) or a control returned by an LDAP server |
| 133 | (<em>response control</em>). Unlike extended requests and responses, |
| 134 | there is not necessarily any pairing between request controls and |
| 135 | response controls. You can send request controls and expect no |
| 136 | response controls back, or receive response controls without sending |
| 137 | any request controls. |
| 138 | <p> |
| 139 | An application typically does not deal directly with this interface. |
| 140 | Instead, it deals with classes that <em>implement</em> this interface. |
| 141 | The application gets control classes either as part of a repertoire of |
| 142 | controls standardized through the IETF, or from directory vendors for |
| 143 | vendor-specific controls. The request control classes should have |
| 144 | constructors that accept arguments in a type-safe and user-friendly |
| 145 | manner, while the response control classes should have access methods |
| 146 | for getting the data of the response in a type-safe and user-friendly |
| 147 | manner. Internally, the request/response control classes deal with |
| 148 | encoding and decoding BER values. |
| 149 | <p> |
| 150 | For example, suppose an LDAP server supports a "signed results" |
| 151 | request control, which when sent with a request, asks the |
| 152 | server to digitally sign the results of an operation. |
| 153 | It would supply a class <tt>SignedResultsControl</tt> so that applications |
| 154 | can use this feature. |
| 155 | An application would use this class as follows: |
| 156 | <blockquote> |
| 157 | <pre> |
| 158 | Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)}; |
| 159 | ectx.setRequestControls(reqCtls); |
| 160 | NamingEnumeration enum = ectx.search(...); |
| 161 | </pre> |
| 162 | </blockquote> |
| 163 | The <tt>SignedResultsControl</tt> class might be defined as follows: |
| 164 | <blockquote><pre> |
| 165 | public class SignedResultsControl implements Control { |
| 166 | // User-friendly constructor |
| 167 | public SignedResultsControl(boolean criticality) { |
| 168 | // assemble the components of the request control |
| 169 | }; |
| 170 | |
| 171 | // Methods used by service providers |
| 172 | public String getID() { |
| 173 | return // control's object identifier |
| 174 | } |
| 175 | public byte[] getEncodedValue() { |
| 176 | return // ASN.1 BER encoded control value |
| 177 | } |
| 178 | ... |
| 179 | } |
| 180 | </pre></blockquote> |
| 181 | <p> |
| 182 | When a service provider receives response controls, it uses |
| 183 | the <tt>ControlFactory</tt> class to produce specific classes |
| 184 | that implement the <tt>Control</tt> interface. |
| 185 | <p> |
| 186 | An LDAP server can send back response controls with an LDAP operation |
| 187 | and also with enumeration results, such as those returned |
| 188 | by a list or search operation. |
| 189 | The <tt>LdapContext</tt> provides a method (<tt>getResponseControls()</tt>) |
| 190 | for getting the response controls sent with an LDAP operation, |
| 191 | while the <tt>HasControls</tt> interface is used to retrieve |
| 192 | response controls associated with enumeration results. |
| 193 | <p> |
| 194 | For example, suppose an LDAP server sends back a "change ID" control in response |
| 195 | to a successful modification. It would supply a class <tt>ChangeIDControl</tt> |
| 196 | so that the application can use this feature. |
| 197 | An application would perform an update, and then try to get the change ID. |
| 198 | <blockquote><pre> |
| 199 | // Perform update |
| 200 | Context ctx = ectx.createSubsubcontext("cn=newobj"); |
| 201 | |
| 202 | // Get response controls |
| 203 | Control[] respCtls = ectx.getResponseControls(); |
| 204 | if (respCtls != null) { |
| 205 | // Find the one we want |
| 206 | for (int i = 0; i < respCtls; i++) { |
| 207 | if(respCtls[i] instanceof ChangeIDControl) { |
| 208 | ChangeIDControl cctl = (ChangeIDControl)respCtls[i]; |
| 209 | System.out.println(cctl.getChangeID()); |
| 210 | } |
| 211 | } |
| 212 | } |
| 213 | </pre></blockquote> |
| 214 | The vendor might supply the following <tt>ChangeIDControl</tt> and |
| 215 | <tt>VendorXControlFactory</tt> classes. The <tt>VendorXControlFactory</tt> |
| 216 | will be used by the service provider when the provider receives response |
| 217 | controls from the LDAP server. |
| 218 | <blockquote><pre> |
| 219 | public class ChangeIDControl implements Control { |
| 220 | long id; |
| 221 | |
| 222 | // Constructor used by ControlFactory |
| 223 | public ChangeIDControl(String OID, byte[] berVal) throws NamingException { |
| 224 | // check validity of OID |
| 225 | id = // extract change ID from berVal |
| 226 | }; |
| 227 | |
| 228 | // Type-safe and User-friendly method |
| 229 | public long getChangeID() { |
| 230 | return id; |
| 231 | } |
| 232 | |
| 233 | // Low-level methods |
| 234 | public String getID() { |
| 235 | return CHANGEID_OID; |
| 236 | } |
| 237 | public byte[] getEncodedValue() { |
| 238 | return // original berVal |
| 239 | } |
| 240 | ... |
| 241 | } |
| 242 | public class VendorXControlFactory extends ControlFactory { |
| 243 | public VendorXControlFactory () { |
| 244 | } |
| 245 | |
| 246 | public Control getControlInstance(Control orig) throws NamingException { |
| 247 | if (isOneOfMyControls(orig.getID())) { |
| 248 | ... |
| 249 | |
| 250 | // determine which of ours it is and call its constructor |
| 251 | return (new ChangeIDControl(orig.getID(), orig.getEncodedValue())); |
| 252 | } |
| 253 | return null; // not one of ours |
| 254 | } |
| 255 | } |
| 256 | </pre></blockquote> |
| 257 | |
| 258 | <p> |
| 259 | |
| 260 | <h2>Package Specification</h2> |
| 261 | |
| 262 | The JNDI API Specification and related documents can be found in the |
| 263 | <a href="../../../../technotes/guides/jndi/index.html">JNDI documentation</a>. |
| 264 | |
| 265 | @since 1.3 |
| 266 | |
| 267 | </body> |
| 268 | </html> |