README 17.4 KB
Newer Older
Steve Sonntag's avatar
Steve Sonntag committed
1

2
LDAP Classes for Java
3
June 2005
Steve Sonntag's avatar
Steve Sonntag committed
4 5

Table of Contents
6 7 8 9 10 11 12 13 14 15 16 17 18
     1.0   LDAP Classes for Java
     2.0   Known Issues and Solutions
     3.0   Dependencies
     4.0   Installation
     5.0   LDAPv2 and LDAPv3 Support
     6.0   Java LDAP Documentation
     7.0   Building JLDAP
     8.0   Building DSML Services
           8.1  dsmlstream.war
           8.2  dsmldom.war
     9.0   Building DSMLv2 & SPML Connection Support
     10.0  Using DSMLv2 Connection Support
     11.0  Using SPML Connection Support
Steve Sonntag's avatar
Steve Sonntag committed
19

20
1.0  LDAP Classes for Java
Steve Sonntag's avatar
Steve Sonntag committed
21 22 23 24 25 26 27 28 29

          LDAP (Lightweight Directory Access Protocol) is
          an emerging Internet standard for accessing directory
          information, allowing LDAP-enabled applications to
          access multiple directories. LDAP v3 supports such
          features as secure connections (through SSL and SASL),
          entry management, schema management, and LDAP controls
          and extensions for expanding LDAP's functionality.

30
          The LDAP Classes for Java enables you to
Steve Sonntag's avatar
Steve Sonntag committed
31 32 33
          write applications to access, manage, update, and
          search for information stored in LDAP-aware directories.

34 35 36 37 38 39
          This API is a work-in-progress implementing the IETF draft 18
          of the Java LDAP API (draft-ietf-ldapext-ldap-java-api-18.txt),
          and as such, most but not all features in the IETF draft are
          currently implemented.  For details, see section 2.0.
          
2.0 Known Issues and Solutions
Steve Sonntag's avatar
Steve Sonntag committed
40

41 42 43 44
     -    The Java LDAP API IETF 18 draft Features not yet implemented.
     
          Classes do not yet extend Serializable
          
45 46
          The API does not return the exception LDAPLocalException in all
          cases where the exception does not originate from the server.
47

48
          The class LDAPExtendedResponse does not yet implement the register
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
          method.
          
          
     -    An incompatibility with previous versions exists for applicatons
          using LDAPSchema.getAtribute() and LDAPSchemaElement.getName().
		  Both methods were deprecated in the May 2002 NDK. These methods
		  have been removed in this release of the API to comply with IETF
		  draft version 18 (draft-ietf-ldapext-ldap-java-api-18.txt).
		  The reason for this change is described in the following text.
          
          LDAPSchema now extends LDAPEntry.  This means that LDAPSchema
		  inherits the getAttribute method from LDAPEntry which has the same
		  signature as the getAttribute method of LDAPSchema, but the two
		  methods differ in functionality.  Thus, the getAttribute method of
		  LDAPSchema has been removed from the IETF draft and from the API
          in this release.

          To fix your application, use the getAttributeSchema method of
          LDAPSchema instead of getAttribute.

          The following error will occur when trying to compile code
          using this deprecated method:
                    incompatible types;
                    found: com.novell.ldap.LDAPAttribute,
                    required: com.novell.ldap.LDAPSchemaElement

          The following error will occur when trying to run code using this
          deprecated method:
                    java.lang.NoSuchMethodError

          LDAPSchemaElement now extends LDAPAttribute.  This means that
		  LDAPSchemaElement inherits the getName method from LDAPAttribute
		  which has the same signature as the getName method of
		  LDAPSchemaElement, but the two methods differ in functionality.
		  Thus, the getName method of LDAPSchemaElement has been removed
		  from the IETF draft and from the API in this release.

          To fix your application, use the getNames method of
          LDAPSchemaElement instead of getName.

          Note: You will not get a compile or runtime error if your code
          uses this deprecated method.  You may, however, get errors trying
          to intrepret the data returned.

3.0  Dependencies
Steve Sonntag's avatar
Steve Sonntag committed
94 95 96

     Building the Java LDAP API is dependent upon the following:

97 98 99 100 101 102 103 104 105 106 107 108
     -    JDK 1.4 or higher, required for building classes that 
          use the new DSML functionality. Optionally, you can use JDK 1.2
          or higher by installing the JAXP package and XML parser and
          by and placing the associated jar files the external directory
          external/jaxp as follows:
                external/jaxp/jaxp.jar
                external/jaxp/xerces.jar

     -    JDK 1.4 or higher, required for building classes that reference
          TLS(SSL) connections. Optionally, you can download a Sun-compliant 
          JSSE implementation to compile with JDK 1.2 or higher and place
          the associated jar files in the external/jsse directory as follows:
109 110 111
                external/jsse/lib/jcert.jar
                external/jsse/lib/jnet.jar
                external/jsse/lib/jsse.jar
Steve Sonntag's avatar
Steve Sonntag committed
112

113 114 115 116 117
     -    The Ant build tool for Java, required for building the product.
          Ant was developed by the jakarta.apache.org project and can be
          obtained from their web site.  We have built this system using
          Ant version 1.5.1 compiled on October 2 2002.

Steve Sonntag's avatar
Steve Sonntag committed
118 119
          The ant tool is placed in the following directory structure
          under the root of the source.
120
                external/ant/LICENSE
121 122 123 124
                external/ant/LICENSE.dom
                external/ant/LICENSE.sax
                external/ant/LICENSE.xerces
                external/ant/welcome.html
125 126 127 128 129
                external/ant/bin/ant
                external/ant/bin/ant.bat
                external/ant/bin/antRun
                external/ant/bin/antRun.bat
                external/ant/bin/lcp.bat
130 131 132 133 134 135 136 137 138 139 140
                external/ant/etc/changelog.xsl
                external/ant/etc/checkstyle-frames.xsl
                external/ant/etc/coverage-frames.xsl
                external/ant/etc/jdepend-frames.xsl
                external/ant/etc/jdepend.xsl
                external/ant/etc/junit-frames.xsl
                external/ant/etc/junit-noframes.xsl
                external/ant/etc/log.xsl
                external/ant/etc/maudit-frames.xsl
                external/ant/etc/mmetrics-frames.xsl
                external/ant/etc/tagdiff.xsl
141
                external/ant/lib/ant.jar
142 143 144
                external/ant/lib/optional.jar
                external/ant/lib/xercesImpl.jar
                external/ant/lib/xml-apis.jar
Steve Sonntag's avatar
Steve Sonntag committed
145

146
     Running an application that uses the LDAP Classes for
Steve Sonntag's avatar
Steve Sonntag committed
147 148
     Java is dependent upon the following:

149 150 151 152 153 154
     -    JRE 1.2 or higher, required to run an application.
          
     -    JDK/JRE 1.4 or higher, required for running appplications that use
          the new DSML functionality. Optionally, you can use JDK/JRE 1.2 or
          higher by installing the JAXP package and setting the associated 
          jar files in your classpath.
Steve Sonntag's avatar
Steve Sonntag committed
155

156 157 158
     -    JDK/JRE 1.4 or higher, required for running applications that create
          TLS(SSL) connections. Optionally, you can download a Sun-compliant 
          JSSE implementation to run with JDK/JRE 1.2 or higher.
Steve Sonntag's avatar
Steve Sonntag committed
159

160 161 162 163 164 165
     -    A directory that supports TLS(SSL), required if you wish to
          run applications that create TLS(SSL) connections.  
          
     -    Novell eDirectory 8.5 or higher, required if you wish to run
          applications that use the LDAP extensions for partition and
          replica management.
Steve Sonntag's avatar
Steve Sonntag committed
166

Steve Sonntag's avatar
Steve Sonntag committed
167
     -    Applications that use com.novell.ldap.util.DSMLReader require
168 169 170
          an XML parser (like xerces.jar) in order to run. This jar file needs
          to be in classpath of the Application.

Steve Sonntag's avatar
Steve Sonntag committed
171

172 173
4.0  Installation

Steve Sonntag's avatar
Steve Sonntag committed
174 175 176 177 178 179 180 181 182
     To install the libraries do the following:
     1. Run the build process outlined below.

     2. Copy the ldap.jar file (either debug or release) to a directory
        of your choice on your platform.

     3. Add the complete path, including the file name, of the
        ldap.jar file to your CLASSPATH.

183
5.0  LDAPv2 and LDAPv3 Support
Steve Sonntag's avatar
Steve Sonntag committed
184

185 186 187 188
          This version of the LDAP Classes for Java supports LDAPv3.
          Since the consensus in the LDAP community is to encourage
          everyone to update to LDAPv3, there is no attempt to ensure
          that these libraries support LDAPv2 servers.
Steve Sonntag's avatar
Steve Sonntag committed
189

190
6.0  Java LDAP Documentation
191 192 193

     Building JLDAP generates javadoc for the Java LDAP Classes.
     There are three directories containing javadoc.  The index.html
194 195
     file is the starting point for the javadoc in each of the directories.
     The directories are:
196 197 198 199 200 201 202 203 204 205 206
     
     pkg/ietfdoc  - contains javadoc for the public classes of the IETF LDAP
                    Java API.  These classes are used by applications needing
                    binary compatibility with Java LDAP implementations from 
                    other vendors.
                    
     pkg/doc      - contains javadoc for the public classes of the Novell LDAP
                    Java API.  These classes provide a richer set of
                    functionality than the IETF classes, and are used by
                    applications needing a full featured API.
                    
207 208 209 210
     doc          - contains javadoc for all classes in the LDAP Java API,
     				and includes package and private methods and variables.
                    This javadoc is typically used by developers developing
                    or modifying the API.
211
                    
212
7.0  Building JLDAP
Steve Sonntag's avatar
Steve Sonntag committed
213 214 215

JLDAP is built using a system developed by jakarta.apache.org called ANT.

Steve Sonntag's avatar
Steve Sonntag committed
216 217
The build files are named "build.xml" and "javac.xml" and are found in the
root directory of the Java LDAP source.
Steve Sonntag's avatar
Steve Sonntag committed
218 219 220 221

To set up your environment for ANT, do the following:

For Win32
Steve Sonntag's avatar
Steve Sonntag committed
222
    Assuming this source directory on win32 is d:\jldap, and java is installed
223
    in d:\j2sdk1.4.1_1 then you set in your environment:
Steve Sonntag's avatar
Steve Sonntag committed
224

225
        set JAVA_HOME=d:\j2sdk1.4.1_1
226
        set ANT_HOME=d:\jldap\external\ant
227 228
        PATH %ANT_HOME%\bin;%JAVA_HOME%\bin;%PATH%

229
For Linux / Unix
Steve Sonntag's avatar
Steve Sonntag committed
230 231 232
    Assuming the following:
        1) A Linux system running bourne shell
        2) The source directory is located in /work/jldap
233
        3) The Java jdk is installed in /usr/local/j2sdk1.4.1_1
Steve Sonntag's avatar
Steve Sonntag committed
234 235
    then export in your environment:

236
        ANT_HOME=/work/jldap/external/ant
237
        JAVA_HOME=/usr/local/j2sdk1.4.1_1
238
        PATH="$ANT_HOME/bin:$JAVA_HOME/bin:$PATH"
Steve Sonntag's avatar
Steve Sonntag committed
239
        export ANT_HOME JAVA_HOME PATH
Steve Sonntag's avatar
Steve Sonntag committed
240

241 242
To build everything except the DSML services, invoke ant as follows from the
top of the source tree:
Steve Sonntag's avatar
Steve Sonntag committed
243

Steve Sonntag's avatar
Steve Sonntag committed
244
    ant all
Steve Sonntag's avatar
Steve Sonntag committed
245

246
Targets available at the top of the source tree are:
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
     clean     - Cleans all generated files and directories in this and
                 subbordinate directories
     cleanpkg  - Cleans pkg directory
     cleanwars - Cleans services/dsml directory 
     doc       - Builds javadoc files
     debug     - Builds debug classes and jar files
     release   - Builds release classes and jar files
     lib       - Builds debug & release classes and jar files
     jar       - Synonym for lib
     all       - Builds everything possible except the DSML services. 
                 This builds in all directories - debug and release jar files,
                 java doc, samples, test programs, and creates an installation
                 directory called pkg.
     install   - Copies build results from all directories and creates the
                 pkg directory
     pkg       - Synonym for install
     war_stream- Builds dsmlstream.war (see 8.0 Building DSML Services)
     war_dom   - Builds dsmldom.war (see 8.0 Building DSML Services)
     wars      - Builds dsmlstream.war and dsmldom.war 
     
267 268
The following directories are created when "ant all" is run:

Steve Sonntag's avatar
Steve Sonntag committed
269
    Contents of directories in the ldap directory
Steve Sonntag's avatar
Steve Sonntag committed
270 271
        jldap/ldap/classes          # Classes used to build lib/ldap.jar 
        jldap/ldap/classes_debug    # Classes used to build lib_debug/ldap.jar 
272
        jldap/ldap/doc              # Developer Javadoc for classes in ldap.jar
Steve Sonntag's avatar
Steve Sonntag committed
273 274 275 276 277 278
        jldap/ldap/lib              # Jar file for ldap - optimized, debug off 
        jldap/ldap/lib_debug        # Jar file for ldap - not optimized, debug on 

    Contents of directories in the jldap/pkg directory
        jldap/pkg                   # Distribution directories and files 
        jldap/pkg/doc               # Javadoc for the Java LDAP API
279
        jldap/pkg/ietfdoc           # Javadoc for the IETF Java LDAP API
Steve Sonntag's avatar
Steve Sonntag committed
280 281 282
        jldap/pkg/lib               # Jar file for ldap - optimized, debug off 
        jldap/pkg/lib_debug         # Jar file for ldap - not optimized, debug on 

283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
8.0 Building DSML Services

The LDAP Classes for Java include functionality that enables an LDAP server to
run as a DSML service. Currently there are two DSML service implementations 
(.war files) that can be generated using the ant build process: dsmlstream.war
and dsmldom.war. See README.dsml for additional information.

     8.1 dsmldom.war
     
     In addition to the dependencies listed in section 3.0, building 
     dsmldom.war is dependent upon the following:
     
     -    Novell eXtend JBroker Web. During the JBroker Web installation, 
          specify the following install location: 
          <javasource_home>/external/JBroker. JBroker Web can be obtained
          at http://developer.novell.com/ndk/jbroker.htm.     

     To build dsmldom.war, invoke ant as follows from the
     top of the source tree:

     ant war_dom

     8.2 dsmlstream.war
     
     In addition to the dependencies listed in section 3.0, building 
     dsmlstream.war is dependent upon the following:
     
     -    servlet.jar. If you have installed JBroker Web, as outlined
          in 8.1, servlet.jar is already installed.  If not, place the
          servlet.jar from your application server (JBroker, tomcat, etc.)
          in the directory <javasource_home>/external/servlet/.
          
315 316 317 318
     NOTE: dsmlstream.war requires an XML parser (like xerces.jar) in order 
           to run. This jar file needs to be in the classpath of the Web 
           Application Server or Servlet engine running dsmlstream.war.
                    
319 320 321 322 323 324 325 326
     To build dsmlstream.war, invoke ant as follows from the
     top of the source tree:

     ant war_stream
          
     You can build both of the above war files by invoking ant as follows:

     ant wars
Steve Sonntag's avatar
Steve Sonntag committed
327

328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
9.0  Building DSMLv2 & SPML Connection Support
     
     The JLDAP libraries provide optional support for using DSMLv2 and SPML in 
     a similar fashion as you would use an LDAP connection.  In order to build 
     support for this functionality into JLDAP you need to add the following 
     libraries to the "ext" directory of your JLDAP source directory:
     
     commons-httpclient-*.jar - http://jakarta.apache.org/site/news/news-2005-q2.html#20050410.1
     openspml.jar & soap.jar - http://www.openspml.org/
     
10.  Using DSMLv2 Connection Support
	 
	 The JLDAP libraries provide optional support for interacting with DSMLv2 based directories 
	 like you would an LDAP directory.  In order to use this functionality, you first create your 
	 DSML connection:
	 
	 DsmlConnection dsmlCon = new DsmlConnection();
	 
	 //Some DSMLv2 implementations do not support SOAP
	 dsmlCon.setUseSOAP(true);
	 //The port is in the URL
	 dsmlCon.connect("http://my.ldap.domain.com:port/path/to/dsmlv2",0);
	 
	 LDAPConnection con = dsmlCon;
	 con.bin("CN=User","secret");
	 .
	 .
	 .
	 
	 Once case to an LDAPConnection, you can perform any synchronouse operation.  Operations that 
	 involve queue's are not supported.  The bind operation includes the bind dn and password in 
	 an HTTP BASIC authentication header.
	 
	 In addtion you may create an implementation of the com.novell.ldap.util.HttpRequestCallback 
	 interface to add HTTP Header variables.
	 
	 The DSMLv2 connection library has been tested with Novell DSMLv2 web services, Octet String 
	 VDE 3.0+ and IBM Tivoli Directory Integrator.
	 
11.  Using SPML Connection Support
     
     The JLDAP libraries provide optional support for the Service Provisioning Markup Language.  
     SPML is a standard for integrating and interacting with provisioning servers.  SPML support
     is provided by the OpenSPML project.  In order to use SPML using JLDAP:

     //Create the connection using a "no auth" implementation.
     SPMLConnection spmlCon = new SPMLConnection("com.novell.ldap.spml.NoAuthImpl");
	 spmlCon.connect("http://my.spml.domain.com/path/to/spml",0);
	 LDAPConnection con = spmlCon;
	 .
	 .
	 .
	 
	 
	 Like the DSMLv2 connection libraries, the SPML libraries only support synchronous operations.
	 As in DSMLv2, there is no BIND operation.  Each SPML implementation has it's own standard.  JLDAP
	 contains support for Sun Identity Manager and OpenSPML implementations.  New authentication 
	 schemes can be implemented by implementing the com.novell.ldap.spml.SPMLImpl interface.
	 
	 When manipluating users, the DN takes the follwing form:
	 
	 IdentityType=name
	 
	 For instance, using the GenericString identifier the DN may be
	 
	 GenericString=myUserName
	 
	 	 
     
Steve Sonntag's avatar
Steve Sonntag committed
397
$OpenLDAP$
398
 ******************************************************************************
399
 * Copyright (C) 1999 - 2003 Novell, Inc. All Rights Reserved.
400 401 402 403 404 405 406 407 408 409
 *
 * THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND
 * TREATIES. USE, MODIFICATION, AND REDISTRIBUTION OF THIS WORK IS SUBJECT
 * TO VERSION 2.0.1 OF THE OPENLDAP PUBLIC LICENSE, A COPY OF WHICH IS
 * AVAILABLE AT HTTP://WWW.OPENLDAP.ORG/LICENSE.HTML OR IN THE FILE "LICENSE"
 * IN THE TOP-LEVEL DIRECTORY OF THE DISTRIBUTION. ANY USE OR EXPLOITATION
 * OF THIS WORK OTHER THAN AS AUTHORIZED IN VERSION 2.0.1 OF THE OPENLDAP
 * PUBLIC LICENSE, OR OTHER PRIOR WRITTEN CONSENT FROM NOVELL, COULD SUBJECT
 * THE PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
 ******************************************************************************