> DNU home > online course > DirXML Driver Development

April 2001

DeveloperNet University Course

Lab 3: Programming Input Parameter Parsing

Module Objective: During this lab, you will add input parameter parsing to the LabDriver's Publisher, Subscriber, and Driver shims.

Important

• You can troubleshoot your program by using printlines similar to the one below:

System.out.println( debugMsgString );

Where debugMsgString is your own debug string. Your debug strings will be sent to DSTrace output where they can help you logically isolate problems in your code.

Do This

1. A working lab driver is required for this lab. Refer to the procedures in Lab 1 if necessary to help you install and configure a lab driver. Once you get the LabDriver working, shut down ConsoleOne and use the NT Services console to shut down eDirectory.

EXPLANATION: During this lab, you will change the functionality in the driver by adding code to its driver shim. It is necessary to shut down the driver because on start-up all class/jar files are read and cached. So, in order for the driver to see new classes/jars, it must be shut down and restarted.

2. Add new directory path location configuration parameters to the LabDriver DirXML driver.

1. Open the file, "C:\DirXMLCrsFldr\Lab1Driver\sources\rules\drvrCfg.xml" in Notepad. It should look like the XML shown below:

---

<?xml version="1.0" encoding="ISO-8859-1" ?> 
<driver-config name="PBX Simulator Driver Shim">
    <driver-options>
            <pbxDBFilePath display-name="PBX Database File Path">
               c:\SolutionLabDriver\pbx\
            </pbxDBFilePath>
           <pbxNDSPath display-name="NDS Context for PBX Objects">
               \TESTTREE\Novell\
           </pbxNDSPath>
    </driver-options>
    <subscriber-options>
    </subscriber-options>
    <publisher-options>
    </publisher-options>
</driver-config>

---

2. If necessary, change the drive letter in the "drvrCfg.xml" from "c:\" to the drive letter you are using. Also, remember to change the tree name from TESTTREE to the name of your tree.
3. Open the property book of the LabDriver object and select the "Driver Parameters XML" panel in the "DirXML Driver Configuration" page, as shown in Figure 1.



Figure 1: Lab1Driver Properties Page

4. Copy the contents of "C:\DirXMLCrsFldr\LabDriver\sources\rules\drvrCfg.xml" into the "Driver Parameters XML" window. Then, click "Apply" and close the property book.
5. Reopen the LabDriver object's property book and select the "Driver Parameters" panel in the "DirXML Driver Configuration" page to view the parsed results of the XML you entered earlier.

EXPLANATION: The XML from the "drvrCfg.xml" file that you copied into the Lab1Driver object was parsed by the DirXML snapin when you committed the change. The values specified by the XML are now editable by the administrator in the Driver Parameters panel. When the driver is started, the DirXML engine will read these parameter values and send them to the driver shim's init( ) method as an XML document input parameter.

In the first two labs, the location of the "pbx" directory accessed by the driver shim is hard-coded into the shim itself, requiring a recompilation of this executable if the directory is ever moved. To make the driver more configurable, in this lab we will add code to the driver shim so that it can parse input parameters to obtain administrator entered directory paths and other information.

The code you add will use W3C's Document Object Model (DOM) industry standard APIs to obtain values from the XmlDocument that is input to the driver shim's init() method. The DOM provides a mechanism for you to programmatically access and manipulate parsed XML content. A partial DOM class hierarchy is shown below:

interface org.w3c.dom.Node
   interface org.w3c.dom.Attr
   interface org.w3c.dom.CharacterData
      interface org.w3c.dom.Comment
      interface org.w3c.dom.Text
         interface org.w3c.dom.CDATASection
   interface org.w3c.dom.Document
   interface org.w3c.dom.DocumentType
   interface org.w3c.dom.Element
interface org.w3c.dom.NodeList

3. Use the following W3C APIs to add code to LabDriverShim.java's init method. The code parses its XmlDocument input parameter and obtains the pathname for the "pbx" directory and the context for the OUs that will contain the pbx's User objects (i.e., "\TESTTREE\Novell\"). (Use the W3C.DOM Javadoc installed on your workstation to get more information.)

Hint: You can use the following APIs to obtain information to print out to DSTrace as you troubleshoot your code:

<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>
      <init-params>
         <driver-filter>
            <allow-class class-name="User">
               <allow-attr attr-name="CN"/>
               <allow-attr attr-name="title"/>
               <allow-attr attr-name="Object Class"/>
               <allow-attr attr-name="lastName"/>
               <allow-attr attr-name="firstName"/>
               <allow-attr attr-name="department"/>
               <allow-attr attr-name="location"/>
               <allow-attr attr-name="phone"/>
            </allow-class>
         </driver-filter>
         <driver-options>
            <pbxDBFilePath display-name="PBX Database File Path">
               C:\DirXMLCrsFldr\LabDriver\pbx
            </pbxDBFilePath>
            <pbxNDSPath display-name="NDS Context For PBX Objects">
               \TESTTREE\Novell\
            </pbxNDSPath>
         </driver-options>
      </init-params>
    </input>
</nds>

First, use XmlDocument's getDocument() method to obtain an instance of a DOM Document. A DOM Document class is a subclass of the DOM Node class. So, obtaining a Document object is actually obtaining the first Node of the tree.

Next, use the Document's getElementsByTagName() method to obtain a NodeList of "pbxDBFilePath" Nodes.

Obtain the "pbxDBFilePath" Node with NodeList's item() method. Notice in "drvrCfg.xml" above that there is only one "pbxDBFilePath" element. Because you expect only one, your code should only look in item (0) for the element. If item (0) is null then the element doesn't exist in the tree.

Next, obtain "pbxDBFilePath" Node's child TextNode with Node's getLastChild( ) method.

Finally, obtain the text value from the child with its getNodeValue() method.

4. Test your driver.

EXPLANATION: Start up the DirXML driver, DSTrace, and ConsoleOne.

The lab driver should poll the "pbx" directory every 4 seconds and print a trace similar to the following in the DSTrace window:

PBXAccountPanel.getDBEvents() called