====================================================================== DSML Tools 1.2.1 Source Release Notes Last updated: April 13, 2005 ====================================================================== For more information on this release, see http://www.dsmltools.org/ Introduction ------------ This software is a suite of tools for working with the Directory Services Markup Language (DSML). It provides the following capabilities: * Querying of an LDAP directory, with search results output as DSML * Import of DSML data into an LDAP directory * Directory-context validation of DSML (no illegal attributes on an entry etc.) * Directory-context diffing of two DSML documents All distributed software in the namespace "org.dsmltools" is dually licensed under the Mozilla Public License (MPL) and the GNU General Public License (GPL). Dependencies ------------ The DSML Tools, as packaged, have four dependencies - Java, Cygwin, the Apache Xerces-J XML Parser and the Netscape Java LDAP client libraries. The GNU Getopt library for Java (binaries and source) is included; it lives at: http://www.urbanophile.com/arenn/hacking/download.html You can find links to the source for all the dependencies at: http://www.dsmltools.org/dependencies.html They are the same links as in this document, but more convenient. * Java The DSML Tools have been tested with the Java SDK version 1.3 on Windows NT and 1.4 on Linux. You can download this from: http://java.sun.com/j2se/downloads.html You'll need to go through their web-based interface to get at the download. Note that this software will not work with Java 1.1, because it uses some Java 2-specific classes (e.g. HashSet). I see no reason why it wouldn't work with Java SDK 1.2, the first release of Java 2. * Cygwin The GNU Tools for Windows (Cygwin) are required to build both Xerces and the Netscape LDAP SDK on Windows. They have a very swish installer, which can be downloaded from: http://www.cygwin.com * Xerces The DSML Tools have been extensively tested with Xerces 1.1.3 (no longer available or supported) and also with Xerces 2.6.2, which claims to be API-compatible. You can download a binary distribution from: http://www.apache.org/dist/xml/xerces-j/ You need to make the classes available to Java - the easiest way to do this is to add the paths to xercesImpl.jar and xmlParserAPIs.jar, which can be found in the root directory of the unzipped tree, to your CLASSPATH environment variable. * Netscape LDAP SDK The DSML Tools have been tested with the Netscape LDAP SDK version 4.1. You can download this from: ftp://ftp.mozilla.org/pub/mozilla.org/directory/java-sdk/ You will either want ldapsdk_java_20000505.zip or ldapsdk_java_20000505.tar.gz . This is a source release, and so needs to be built (after applying the fix detailed below). Build instructions are included. Note that building this software under Windows requires some Netscape-specific tools in addition to Cygwin. These are detailed in the build instructions. Be sure to follow them carefully. If, after building, you execute the additional command to make a jar file, you can add it to your CLASSPATH in the same manner as above. The jar file ends up as: %INSTALL_POINT%/directory/java-sdk/dist/bin/ldapjdk.jar Fixes Needed ------------ I have had to patch files in the Netscape package. You will need to copy the modified source files on top of those in the unzipped tree before building. The files for these fixes are found in the fixes directory of the distribution. The first fix allows the DSML Tools to get schema information from non-Netscape directories. This bug has been reported to the maintainers (http://bugzilla.mozilla.org/show_bug.cgi?id=52775) and fixed in their CVS, but there has not been an official release since. The second fix works around a bug in DC-Directory (and perhaps other directories) which do special processing for (objectclass=*) but don't recognise (|(objectclass=*)(objectclass=ldapsubentry)). Change to directory/java-sdk/ldapjdk/netscape/ldap/ and execute: patch < path/to/dsmltools/fixes/LDAPConnection.diff patch < path/to/dsmltools/fixes/LDAPSchema.diff Directory Compatibility ----------------------- The DSML Tools have been tested with OpenLDAP 2, Netscape Directory Server and DC-Directory. They should work with any directory that supports LDAP v3. Users of DC-Directory will need v2.4, build 20001002 or later. Installation ------------ Merely unpack the zip into a new directory. The unpack will create a directory called "dsmltools" and put the files in it. Build Instructions ------------------ Build the software by changing to the dsmltools/src directory and typing "make". This will create .class files, javadoc and a .jar as well. Add the resulting dsmltools.jar to your CLASSPATH in the normal way. Usage Instructions ------------------ Once you've installed the software and all the dependencies, and made sure that all the correct .jar files have been added to your classpath, you run the software as follows: java org.dsmltools. where is one of LDAP2DSML, DSML2LDAP, DSMLDiff and DSMLValidate. Please see the javadoc documentation for usage instructions for the software. Each of the programs should be explained on the javadoc page for that class. Alternatively, passing the option '-?' or '--help' will produce usage information. Note: If the DSML Tools believe that your DSML, or the data returned by your directory, is invalid (and validation is turned on) it will attempt to fix the problems, while writing errors to stderr. Many directories on the market today violate standards and so the DSML Tools may object to the information they return in this way. If this is a problem for you, you can turn validation off with the '-q' option. Source Code Notes ----------------- The released form of this code is a preprocessed version (using a proprietary preprocessor owned by Data Connection Limited) of the actual source which I wrote. The main effects of this preprocessor are to remove tracing, and convert their comment forms into proper Javadoc comments. This means that occasionally in the code you will find empty "else" branches, double blank lines, or other artifacts of this removal. If you plan to send patches, please try and avoid the temptation to "tidy" the code by changing these as it makes applying the patches more difficult :-) Because this code is Open Source, and preprocessing it probably counts as a Modification, you can also download the un-preprocessed version from: http://www.dsmltools.org/source/ This way, I can avoid license trouble with using patches submitted against the preprocessed version in the original version. However, please don't download it, as it won't compile and will just waste my bandwidth :-) Note that I will only be able to accept patches which are MPL/GPL dual-licensed, as this code is. Submitting a patch constitutes agreement to this :-) Changelog --------- See the file HISTORY. Gerv This product includes software developed by the Apache Software Foundation (http://www.apache.org/).