DirXML Drivers, Engine and Story
Articles and Tips: article
Senior Research Engineer
Novell AppNotes
01 Nov 2001
In the October issue, we covered the changes in Novell eDirectory between the version that released with NetWare 5.x and NetWare 6. Previous to the October issue, we were discussing using DSTRACE.
In the September issue, we covered using DSTRACE to do something useful, and I hinted at the possibility of the next issue talking about setting up and debugging a DirXML driver using DSTRACE. However, as I thought about this, I figured it may not be so good to dive right into debugging a DirXML driver without first giving a little background about the DirXML engine and DirXML drivers.
So without insulting anyone's intelligence, I would like to go through a question and answer session about the DirXML engine and the DirXML driver interface before tackling debugging a DirXML driver. The rest of this Q&A will be covered next month.
What is DirXML?
DirXML is a product for Novell eDirectory 8.x and greater. DirXML makes possible the synchronization of data between Novell eDirectory and other directory services or applications.
The DirXML product contains the following components:
DirXML Driver Infrastructure
DirXML Drivers
ConsoleOne Snap-ins for DirXML administration
DirXML allows an application to do the following:
Share data with eDirectory
Synchronize that data to eDirectory when modified in the application database
Synchronize that data to the application when modified in eDirectory
If you choose to use multiple applications utilizing DirXML to synchronize with eDirectory, DirXML will synchronize shared data with all the applications. Figure 1 shows this concept.
DirXML exchanging data
The flexibility and simplicity of DirXML is derived from the following features:
XML. T
he DirXML engine converts eDirectory data and modification events in XML documents that can be easily read by other applications.
Associations.
DirXML does not need to share a unique ID with the other application. Rather, it uses an association attribute which associates an eDirectory object with whatever the external application uses to identify a unique record.
Schema Mapping.
This feature allows an eDirectory attribute to be associated with a corresponding file in the external application. For example, the eDirectory Surname can be mapped to a Last Name field.
Authoritative Data Sources.
eDirectory rights determine which application has sufficient rights to update an attribute or an entry.
Create Rules.
Each application that is being synchronized with eDirectory might have different conditions for creating a new entry. The Create Rule feature controls the creation of entities in both eDirectory and the synchronizing application.
Selected Data.
Most applications store information that is specific to the application. DirXML allows only selected specific data to be shared.
Data Transformations.
DirXML handles data transformations to ensure that dates of one format are consistent with other formats. This is true for all format specific data.
DirXML Engine.
The DirXML engine is responsible for eDirectory's communication, schema mapping, rule enforcement, and data filtering. Since the engine does most of the work, the DirXML driver has only two main responsibilities: communicating with the application and notifying the DirXML engine when events occur in the application.
DirXML Architecture
The DirXML engine is the key module in the DirXML architecture and provides the interface that allows DirXML drivers to synchronize external application information with eDirectory. Figure 2 Illustrates the interactions between a DirXML driver, the DirXML engine, eDirectory, and an external database.
DirXML Engine, Driver, eDirectory and External Application
When eDirectory initializes, it reads the event filter, registers the driver for the appropriate eDirectory events, filters the data according to the filter's specification, and sets up a cache to the events. eDirectory then notifies the DirXML engine when an event occurs. The DirXML engine reads all of the rules you have set up for the subscription shim of your driver (such as event transformations, matching, placement, create, mapping, and output style) and sends the data to your subscription shim.
The subscriber portion of your driver is responsible for the following tasks:
Data Conversion
Event Transform Rules
Data Sending
Response Handling
The publisher portion of your driver performs the gathering and sending of updates from the external database to eDirectory. The following tasks are driver-implemented specific:
Changing data
Filtering data
Converting data
Sending data
Questions About Design
The DirXML driver acts as the link between your external application or directory and eDirectory. The following are some questions that might be asked when designing a DirXML driver.
Q.
How does a driver fit into the DirXML framework?A.
DirXML can be thought of as two separate black boxes called channels. Each channel takes an event on it input and issues a set of command on its output. The goal of the transformation from events to commands is to propagate the changes made by the application connected to the channel input into the application connected to the channel output. The transformation involves fixed logic in DirXML together with a set of configurable rules that guide the transformation of event to commands.Q.
What are the responsibilities of a driver?A.
A driver does only what DirXMl tells it to do (through the Subscription shim).A driver reports to DirXML any relevant events that occur in the application (through the Publication shim).
Q.
Does a driver need to know anything about rules?A.
No. It is useful for the driver writer to understand what rules do, but the driver has no responsibility for rules processing. The driver writer should have a good understanding of the responsibilities of the driver before worrying about rules.Q.
What is association?A.
Associations are the mechanism used by which DirXML establishes and maintains a correspondence between an object in eDirectory and an application object. The driver provides a unique key value for each object and to notify DirXML of those key values in eDirectory.Q.
How does DirXML communicate with the driver?A.
DirXML communicates with a driver through interfaces. In Java these are represented by Java interfaces. In C++ these are represented as pure abstract base classes. In order to keep this document somewhat short, I will focus on the Java interfaces. C++ interface documentation is available through http://developer.novell.com.Q.
What interfaces are implemented by the driver?A.
Here are the following interfaces:DriverShim. The top-level interface responsible for starting up and shutting down the driver.
SubscriptionShim. The interface responsible for accepting and processing commands from DirXML.
PublicationShim. The interface responsible for notifying DirXML of events that occur in the application.
XmlQueryProcessor. The interface passed by the PublicationShim into XmlCommandProcessor.execute() when calling DirXML to report an application event.
Q.
What interfaces are implemented by DirXML?A.
Here are the following interfaces:XmlCommandProcessor. The interface passed to PublicationShim.start() so that the PublicationShim can notify DirXML of application events.
XmlQueryProcessor. The interface passed by DirXML to SubscribeShim.execute() so that the SubscriptionShim can query DirXML for additional information it may need to process a command.
Q.
How are these interfaces used?The object implementing DriverShim is instantiated by DirXML via introspection using a no-argument constructor.
The DriverShim.init() method is called by DirXML. DirXML passes in the driver initialization parameters.
DirXML retrieves the object implementing the SubscriberShim interface using DriverShim.getPublicationShim().
DirXML retrieves the object implementing the PublicationShim interface using DriverShim.getPublicationShim().
DirXML calls SubscriptionShim.init(), passing the Subscriber initialization parameters.
A separate Publisher thread is created. In the Publisher thread:
DirXML calls PublicationShim.init(), passing the Publisher initialization parameters.
DirXML calls PublicationShim.start(), passing the DirXML object that implements XmlCommandProcessor. The PublicationShim.start() method loops, notifying DirXML using XmlCommandProcessor.execute() whenever a relevant event occurs in the application.It does not return until DriverShim.shutdown() is called, unless there is a fatal error.
XmlCommandProcessor.execute() processes the event, possibly calling the driver XmlQueryProcessor(passed into XmlCommandProcessor.execute()) one or more times if additional information is needed by DirXML to process the event.
At this point, DirXML monitors eDirectory for relevant events and invokes Subscription Shim.execute() when an application object must be created or a change must be made to an application object. In addition, DirXML invokes SubscriptionShim.execute() to query the application for information about application objects. SubscriptionShim.execute() processes the command, optionally calling the DirXML XmlQueryProcessor(passed into SubscriptionShim.execute()) one or more times if additional information is needed to process the command.
At some time in the future eDirectory sends DirXML an event telling DirXML to shut down the driver. DriverShim.shutdown() is called, which performs whatever driver-specific cleanup is needed (including signaling the PublicationShim to return from start().)
Q.
What is the XmlDocument used by the interfaces?A.
XmlDocument is a high level abstraction representing an XML document. It allows for easy conversions between several common representations of XML, notably Document Object Model (DOM), Simple API for XML 1.0 (SAX), and a serialized, human-readable form.Q.
How do I create a DOM document?A.
The implementation of DOM used by DirXML is provided by nxsl.jar (which contains Novell's XSLT processor as well as many XML utility classes.) To create a document that uses the same implementation as DirXML, use the com.novell.xml.dom.DocumentFactory.new Document().Q.
What is the structure of the XML documents that passes to and from the various interface methods?A.
The documents passed to and from the various methods have a structure defined by nds.dtd. All documents use <nds> as the document (top-level) element, which may contain an optional <source> element. Documents that are passed as parameters to interface methods also contain a single <input> element that contains an arbitrary number of events or commands as applicable.Documents that are returned from interface methods contain a single <output> element which contains the results of the processing the events or commands contained in the input document and may contain a limited set of commands.
For example, if the DirXML sends:
<nds dtdversion="1.0" ndsversion="8.5">
<source>
<product asn1id="2 16 840 1 113719 1 x" version="1.0b3"
>DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<! - input commands or events go here -- >
</input>
</nds>
The Shim returns:
<nds dtdversion="1.0" ndsversion="8.5">
<source>
<product version="1.0b3">Some Application Driver</product>
<contact>Nobody in particular</contact>
</source>
<output>
<! - results from commands or events go here -- >
</output>
</nds>
Q.
What is the difference between events and commands?A.
The distinction is subtle but important. Many of the possible child elements of <input> can be interpreted either as commands or as events, depending on the context, and have essentially the same syntax. In general, for elements that can be used as either a command or as notification of an event, the following applies:If the element is being sent to the driver, the element is a command; and if the element is being sent to DirXML, the element is an event notification.
When the driver sends an event notification to DirXML, the driver is informing DirXML of something that occurred in the application. DirXML will then determine, based on configurable rules, what commands, if any, must be sent to eDirectory.
When DirXML sends a command to the driver, DirXML has already taken an eDirectory event as input, applied the appropriate rules, and determined that the change in the application is represented by the command is necessary.
Q.
What are rules?A.
Rules help DirXML transform an event or channel input into a set of commands on the channel output. All rules can be implemented using XSLT stylesheets, but rules that perform well-defined roles more commonly use a DirXML-specific XML format that more easily describes the transformation needed.Rules stores in theXmlData attribute of the DirXML-Rule and DirXML-Stylesheet objects. The DirXML-Driver, DirXML-Subscriber, and DirXML-Publisher objects have attributes that reference rule objects.
Q.
What does the Schema Mapping Rule do?A.
The Schema Mapping Rule is referenced by the driver object and applies to both the Subscriber channel and to the Publisher channel. The purpose of the Schema Mapping Rule is to map schema names between the eDirectory namespace and the application namespace.Q.
What does the Input Transformation Rule do?The Input Transformation Rule is referenced by the driver object and applies to both the Subscriber channel and to the Publisher channel. The purpose of this rule is to perform any preliminary transformation on all XML documents that are sent to DirXML by the driver and are returned to DirXML from the driver.
The Input Transformation Rule is applied to the XML document sent to XmlCommandProcessor.execute() and XmlQueryProcessor().query()(when called by the driver) and to the XML document that returned from a SubscriptionShim.execute() call and/or a XmlQueryProcessor().query() (when called by DirXML). The Input Transformation rule is applied before the Schema Mapping Rule.
Q.
What does the Output Transformation Rule do?A.
The Output Transformation Rule is referenced by the driver object and applies to both the Subscriber channel and to the Publisher channel. The purpose of this rule is to perform any final transformation necessary on the XML documents that are sent to the driver. Functionality is very similar to the Input Transformation Rule, except it is applied to the output.Q.
What does the Event Transformation Rule do?A.
An Event Transformation Rule may be referenced by the Subscriber object and/or the Publisher object. The purpose of an Event Transformation Rule is to perform preliminary transformations on events. The Event Transformation Rule is always implemented using an XSLT stylesheet.There are are many common applications for the Event Transformation Rule, including:
custom event filtering;
changing the event type;
transforming the event directly into a custom command to be passed to the application;
and generating additional events.
Q.
What does the Matching Rule do?A.
A Matching Rule may be referenced by the Subscriber object and/or the Publisher object (typically the Subscriber and Publisher would reference different rule objects.) The purpose of the Matching Rule is to automatically associate objects in eDirectory with objects in the application. The rule syntax is defined by the documentation for <matching-rules>. The matching rule is only applied to <add> events.Q.
What does the Create Rule do?A.
The Create Rule can be referenced by the Subscriber object and/or the Publisher object. The purpose of the Create Rule is to decide whether or not to create a new object if a suitable association could not be automatically generated by the Matching Rule.A Create Rule also can perform other modifications to the <add> event such as providing default values for attributes and/or specifying an object to use as a template for creating the new object.
Q.
What does the Placement Rule do?A.
The purpose of the Placement Rule is to determine where in the storage hierarchy to place an object that is to be created and to determine the name for the new object. For eDirectory and other directory applications, this means generating a distinguished name for the new object. The Placement Rule is only applied to <add> events which were not "vetoed" by the Create Rule.Q.
What does an Event Filter do?A.
An Event Filter specifies the classes of objects and the attributes of those objects for which DirXML will process events. Separate event Filters are specified for the Subscriber and Publisher channels. Event Filters only pass events on objects whose effective class matches one of those classes that are specified by the filter. Event Filters do not pass events on objects that are a subclass of a class specified in the filter unless the subclass is also specified.Q.
What is the general flow of an event through the Event Filter and rules?A.
The following is the general order of rule processing. Note that this is an extreme over-simplification of the processing that actually occurs and that processing may stop at any point or skip to the last step if the results of processing a rule dictates it.Subscriber Channel:
Event generated by eDirectory.
Filter event using Subscriber Event Filter.
Apply Event Transformation Rule.
If event is <modify> on unassociated object, convert to <add>.
If event is <add>
Apply Matching Rule.
Apply Create Rule.
Apply Placement Rule.
Apply Schema Mapping Rule.
Apply Output Transformation Rule.
Send command(s) to driver.
Publisher Channel:
Event sent to DirXML by the driver.
Apply Input Transformation Rule.
Apply Schema Mapping Rule.
Apply Event Transformation Rule.
Filter event by the Publisher Event Rule.
If event is <modify> on unassociated object, convert to <add>.
If event is <add>
Apply Matching Rule.
Apply Create Rule.
Apply Placement Rule.
Send command(s) to eDirectory.
Continued next issue...
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.