DSMLv2/SOAP Support for eDirectory
October 2003


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/

Table of Contents

1.0  Dependencies

2.0  What This Kit Contains

3.0  Deployment
     3.1  exteNd JBroker Web
     3.2  exteNd Application Server
     3.3  Jakarta Tomcat 4

4.0  Samples
     4.1  JBroker
     4.2  JNDI

5.0  Configuration

6.0  Enabling TLS (SSL)

7.0  Revision History
     7.1  October 2003 Release
     7.2  June 2003 Release
          7.2.1  New Functionality
          7.2.2  Bug Fixes
     7.3  March 2003 Release

8.0  Documentation Conventions

9.0  Legal Notices


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.

              Download and install exteNd Application
              Server. 
           1. See
              http://developer.novell.com/ndk/exappserver.h
              tm for information.
              Download and install exteNd Workbench. 
           2. See
              http://developer.novell.com/ndk/exworkbench.h
              tm 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.

              Download and install Jakarta Tomcat. 
           1. 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/dat
     a/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  October 2003 Release

     7.2  June 2003 Release

          7.2.1  New Functionality

                 New samples added in the
                 samples/dsml_consumers directory.


          7.2.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.3  March 2003 Release

          Initial release


8.0  Documentation Conventions

     In this documentation, a greater-than symbol (>) is
     used to separate actions within a step and items in a
     cross-reference path.

9.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 © 2003 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.



