The following sections describe the decisions you need to make before you start coding:
Writing an application driver for DirXML requires a thorough understanding of the target application, including the application’s schema, APIs, authentication, and access requirements. The following areas must be considered.
Application Programming Interfaces (APIs). The APIs of an application are the methods through which your driver will communicate with the application for the purposes of modifying and querying data. These may include access methods such as LDAP or direct function calls through an application-supplied library. The choice of API (when there is one) affects how your driver can be used. For example, if your application supports both a function-call interface and an IP interface, choosing the function-call interface may restrict your driver to running on the same physical server as the application.
Authentication or Log on. Many applications require both users and programs to authenticate or log on to the application before data may be accessed. You must be familiar with the authentication requirements of your application. DirXML provides a secure way to store an application's password in eDirectory on behalf of your driver, and provides standard locations for specifying other connection and authentication parameters which are passed to your driver as part of the initialization procedure.
Change Notification Mechanism. Publishing data to eDirectory from the application requires determining when data change in the application. The application may support an event notification system or a polling mechanism. The application may not directly support any method of notification; in such cases you will have to design a method using the tools the application provides.
Association Values. A DirXML association value is a value that uniquely identifies an object or record in the application. The association value can be anything that uniquely identifies the object; it is most convenient if the value is invariant, such as a record number or a GUID (Global Unique Identifier). However, it is possible to use values that change (such as a distinguished name) but your driver must be carefully written to inform DirXML when such an association value changes by publishing a <modify-association> event with the old and new association values. Examples of association values used by Novell-written drivers include the following: GUID (NDS to NDS and Active Directory drivers), DN (iPlanet directory server driver), and User Name (NT 4 domain driver).
The Extensible Markup Language (XML) is a standard issued by the World Wide Web Consortium that describes how data are marked up using application defined tags and attributes. All communication of data between the DirXML engine and the application driver is in the form of XML documents. An XML document is a collection of data, tree-like in structure, with the data being marked by XML tags and attributes.
DirXML supports two standard interfaces for accessing and manipulating XML data: the Document Object Model (DOM) and the Simple API for XML (SAX). In addition, DirXML provides access to XML documents in serialized form. Serialized XML, however, is the least convenient way of representing XML data for programmatic use.
The DOM presents a tree-like view of the XML document and is typically the most convenient way to access and manipulate XML data programmatically. SAX presents XML documents as a series of events for which handlers are registered. SAX is typically used when only a small part of an XML document is interesting and when navigation among the XML data is not required.
Novell also provides an API designed to make handling DOM documents much easier, called XDS Libraries. The elements in a DOM tree are abstracted to a Java API making it easier to access XML data, as well as construct valid xml documents and driver parameters.
The following table outlines several advantages and disadvantages to each XML interface. There are also many resources on the Internet to aid in determing which XML interface better suits your driver requirements.
The XML documents used for communication between the DirXML engine and the application driver have well-defined tags and attributes for describing the data. The "flavor" or "dialect" of XML used is specific to DirXML and is often referred to as XDS (XML Directory Services).
You must decide whether to write your application driver in Java or in C++. In general, Java is the preferred choice because using Java allows your driver to run on all of the platforms on which DirXML runs. For example, the Novell NDS to NDS driver is written in Java and runs unchanged (using the same .jar file) on all of the platforms on which DirXML runs (currently Windows NT, Windows 2000, Netware 5.x, Solaris, and Linux).
In addition, choosing Java as your implementation language relieves you of the memory management issues associated with C++.
However, there are instances where writing a C++ driver makes more sense. Reasons may include the lack of a suitable interface to the application easily usable from Java or application programming tools provided only in C or C++.
The interfaces that your driver must implement are found in the header file NativeInterface.h.
The DirXML SDK provides a number of utility functions to perform common tasks necessary in your driver. These include factory functions for creating concrete implementations of various DirXML interfaces and support for creating DirXML-specific XML documents. The utility functions may be found in the following header files: InterfaceFactory.h, Trace.h, NdsDtd.h, Base64Codec.h, UTFConverter.h, and DriverFilter.h.
There are no standard language bindings for the DOM and SAX to C++. Therefore, Novell provides a binding for these two interfaces. The language binding for DOM is found in dom.h. The language binding for SAX is found in sax.h. Factories for creating concrete DOM objects and SAX implementations are found in InterfaceFactory.h.
In order to use the factories and utility functions it is necessary to link your application with the appropriate import library for your platform.
|
Library |
Platform |
|---|---|
|
dirxmllib.lib |
Win32 (NT and Windows 2000) |
|
dirxml.imp |
NetWare |
|
libdirxml.so |
Solaris, Linux, and Tru64 Unix |
For more information about these functions, see XML Interfaces for C++.
The interface definitions and utility classes provided by DirXML are found primarily in the package com.novell.nds.dirxml.driver. In addition, many useful classes may be found in the XML/XSLT support packages such as com.novell.xml and descendants. For more information, see the javadocs.
There are standard language bindings for the DOM interface and for the SAX interface supported by DirXML. These bindings are found in org.w3c.dom and org.xml.sax.
The DirXML classes are found in dirxml.jar and nxsl.jar; you will need to include these .jar files in your class path.
You should compile your Java driver against JDK version 1.1.7b because that is the latest version of Java supported on NetWare at the time of the initial DirXML release. This means that you cannot use Java 2 features if you want your driver to run on NetWare systems.
Note that in DirXML 1.1, you can add a new jar file without shutting down eDirectory. You will still need to shut down eDirectory to update an existing jar file.
The following sections outline the suggested steps for writing a DirXML driver. The instructions start with setting up the skeleton driver, which is used as sample code for the rest of the instructions. The instructions then explain how to develop the driver object and the required interfaces:
Novell recommends developing the subscriber channel first since this channel will help you work out communication issues with the application, schema differences, and the conversion of XML commands to application commands. The publication channel requires you to deal with these issues as well as ensuring that the XML documents created by your driver include all the required information.
This chapter also includes information about the following topics: