DSML for eDirectory (SOAP)

Overview

DSMLv2/SOAP is an OASIS standard for representing directory information as XML. DSMLv2/SOAP provides your application with a standard way to present and transfer directory information in XML format.

The DSMLv2/SOAP specification provides both a DTD and a schema for reference. These reference materials along with the DSMLv2 specification are available from OASIS at http://www.oasis-open.org/committees/dsml/

1.0 Dependencies

Developing and running an application that uses DSMLv2/SOAP support for eDirectory requires the following:

• A Web Application Server or Servlet engine, such as exteNd JBroker Web, Novell exteNd Application Server, or Jakarta Tomcat version 4 (Tomcat 3 is not supported).
• JRE 1.4 or higher, required to run an application.
• JDK 1.4 or higher, required to develop applications.
• An LDAP Server. If you wish to use TLS (SSL) or Start/Stop TLS functionality, you need an LDAP server that supports these features. Novell eDirectory 8 or higher supports SSL, and Novell eDirectory 8.7 supports Start/Stop TLS.
• Novell eDirectory 8.5 or higher if you wish to develop or run applications that use the LDAP extensions for partition and replica management.

2.0 What This Kit Contains

This kit consists of a deployable web archive (.war) file, called novell-dsml.war, containing the necessary .jar files and .xml configuration files to run DSMLv2/SOAP support on your Web application server, as well as a readme and several sample files to get you started using DSMLv2/SOAP support.

3.0 Deployment

This section guides you through deploying Novell DSMLv2/SOAP support for eDirectory on exteNd JBroker Web, exteNd Application Server and Jakarta Tomcat 4.

3.1 exteNd JBroker Web

The following steps guide you through deploying Novell DSMLv2/SOAP support for eDirectory on exteNd JBroker Web.

1. Download and install exteNd JBroker Web. See http://developer.novell.com/ndk/jbroker.htm for information.
2. Deploy the novell-dsml.war file on JBroker using the jwebserv executable.
3. Browse to http://[urltoservice]/jbroker, where [urltoservice] is the URL where the DSMLv2/SOAP support is deployed (this URL might contain a port). If the DSMLv2/SOAP service is installed properly you will see a verification page.
4. By default, the Web.xml configuration file is set up to access www.nldap.com, which can be used to run DSMLv2/SOAP samples.

3.2 exteNd Application Server

The following steps guide you through deploying Novell DSMLv2/SOAP support for eDirectory on exteNd Application Server.

1. Download and install exteNd Application Server.
   See http://developer.novell.com/ndk/exappserver.htm for information.
2. Download and install exteNd Workbench.
   See http://developer.novell.com/ndk/exworkbench.htm for information.
3. In Workbench, deploy the file by creating a new project of type "deploy only" and specify the novell-dsml.war file.
4. Create a deployment plan and set deployment properties.
5. Deploy the DSMLv2/SOAP service to your exteNd Application Server (or another Web application server).
6. By default, the Web.xml configuration file is set up to access www.nldap.com, which can be used to run DSMLv2/SOAP samples.

3.3 Jakarta Tomcat 4

The following steps guide you through deploying Novell DSMLv2/SOAP Support for eDirectory on Jakarta Tomcat 4.

1. Download and install Jakarta Tomcat.
   See http://jakarta.apache.org/tomcat/ for information.
2. Deploy the novell-dsml.war file on Tomcat by placing the file in the tomcat\webapps folder.
3. Start or restart Tomcat. When Tomcat loads, the novell-dsml.war file is found and expanded on your server.
4. Browse to http://[urltoservice]/novell-dsml/, where [urltoservice] is the URL where your Tomcat installation is running (this URL might contain a port). If the DSMLv2/SOAP service is installed properly you will see a verification page.
5. By default, the Web.xml configuration file is set up to access www.nldap.com, which can be used to run DSMLv2/SOAP samples.

4.0 Samples

DSMLv2/SOAP support is bundled with several samples to get you up and running quickly. This kit contains two sample types; JBroker and JNDI.

Once the DSMLv2/SOAP service is running on your application server complete the following steps to run these samples.

4.1 JBroker

The JBroker samples will run once you have deployed the DSMLv2/SOAP Service to your application server. To test the JBroker samples, browse to http://[urltoservice]/novell-dsml/, where [urltoservice] is the URL where your application server is running (the URL might require a port number). If the DSMLv2/SOAP service is installed properly you will see a verification page.

An additional JBroker sample, called DomClient, is included with this kit. Both samples use a stub and service generated by JBroker from the DsmlClient.java interface.

From the folder containing the deployed novell-dsml.war file, browse to WEB-INF\classes, which contains a compiled version of this sample. To run this sample, execute the following command:

java sample_consumers.DomClient [dsmlfile] [urltoservice]

Where, [dsmlfile] is any DSMLv2 file (an example, dsml.xml, is included in novell-dsml.war) and [urltoservice] is the URL of the DSMLv2/SOAP service (this URL might require a port number) on your application server. This program reads the DSMLv2 file as DOM and sends the request XML to the service.

The source code for this sample is contained in the novell-dsml\src folder.

4.2 JNDI

To run the samples that use JNDI you need the following:

• Java XML Summer Pack. This is available from Sun at http://java.sun.com/xml/downloads/javaxmlpack.html
• JNDI DSMLv2 Service Provider. This is available from Sun at http://java.sun.com/developer/earlyAccess/jndi/

The following .jar files, which are contained in the previous downloads, must be specified in your classpath:

• dsmlv2.jar
• providerutil.jar
• saaj-api.jar
• activation.jar
• dom4j.jar
• saaj-ri.jar
• mail.jar
• commons-logging.jar

From the folder containing the deployed novell-dsml.war file, browse to WEB-INF\classes, which contains a compiled version of the JNDI sample. To run this sample, execute the following command:

java sample_consumers.Search [urltoservice] [logindn] [password] [searchdn] [searchfilter]

Where [urltoservice] is the URL of the DSMLv2/SOAP service running on your application server (this URL might require a port).

The source code for this sample is contained in the novell-dsml\src folder.

Additionally, you can modify any of the JNDI samples contained in the LDAP Controls and Extensions for JNDI (available at http://developer.novell.com/ndk/extjndi.htm) to use the DSMLv2/SOAP service by performing the following:

Open a sample and modify the context factory environment variable.

Change: com.sun.jndi.ldap.LdapCtxFactory

to: com.sun.jndi.dsmlv2.soap.DsmlSoapCtxFactory

See the source code for Search.java for an example.

5.0 Configuration

Novell DSMLv2/SOAP support for eDirectory is configured using the WEB-INF\Web.xml. This file contains several parameters enabling you to customize the behavior of the DSMLv2/SOAP service. These parameters are documented within the Web.xml file.

6.0 Enabling TLS (SSL)

In order to use TLS (SSL) with DSMLv2/SOAP support you must create a keystore. For instructions on creating a keystore, see the LDAP Classes for Java documentation at http://developer.novell.com/ndk/doc/jldap/jldapenu/data/cchcbejj.html JSSE and the keytool are included with JDK 1.4.

Once this keystore is created, the path is specified in the ldapKeystore parameter in the Web.xml configuration file:

<context-param>

<param-name>ldapKeystore</param-name>

<param-value></param-value>

</context-param>

7.0 Revision History

7.1 June 2004 Release

7.1.1 New Functionality

• Support for eDirectory events exposed using LDAP.
• New event listener interface for persistence search.
• New event listener interface for eDirectory events.

7.1.2 New Sample Code

• Demostrating use of eDirectory events with and without the event listener interface.
• Demostrating use of the new persistence search listener interface.

7.1.3 Bug Fixes

• DSMLWriter did not support pre-defined entities in XML (<, > ).
• The LDAP URL fails to parse attribute correctly.
• DSMLReader is not reading extended response with error message.

7.2 February 2004 Release

7.2.1 Bug Fixes

The following bugs were fixed as part of the February 2004 NDK release:

• Request with processing=parallel, responseOrder=unordered without the requestID was giving an error.
• Not getting proper response for DSML request when syntax errors occurred.
• ModifyResponse was not responding with the same requestID in the response.

7.3 October 2003 Release

7.3.1 New Functionality

New samples directory (dsmlsamples) added in the samples directory.

Added following samples and xml files in this new directory:

• DSMLSoapClient.java Sample DSMLClient written using java to access DSML v2/SOAP for eDirectory
• Following XML files were added representing DSML operation
  • AddRequest - Sample XML file representing DSML Add Request
  • ModifyRequest - Sample XML file representing DSML Modify Request
  • DelRequest - Sample XML file representing DSML Delete Request
  • ModDNRequest - Sample XML file representing DSML ModDN Request
  • SearchRequest - Sample XML file representing DSML Search Request

7.3.2 Bug Fixes

• com.novell.ldap.util - Fixed the xsi namespace prefix problem in the DOMWriter class.

7.4 June 2003 Release

7.4.1 New Functionality

New samples added in the samples/dsml_consumers directory.

7.4.2 Bug Fixes

• com.novell.ldap.util - Fixed namespace problems in the DomReader class.
• com.novell.ldap.util - The DomWriter class returned a vague error message when invalid credentials were supplied. Fixed this problem.
• com.novell.ldap.util - The DomHandler class sometimes generated an exception when processing complex search filters with a substring matching expression, followed by another search expression. Fixed this problem.

7.5 March 2003 Release

Initial release

8.0 Legal Notices

Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.

You may not export or re-export this product in violation of any applicable laws or regulations including, without limitation, U.S. export regulations or the laws of the country in which you reside.

All files provided in this release are subject to the Novell Developer Kit license Agreement and Separate Limited Warranty, which can be found in the license.txt file provided in this download.

Copyright ^© 2004 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Novell is a registered trademark of Novell, Inc. in the United States and other countries.

All third-party trademarks are the property of their respective owners.