> DNU home > online course > DirXML Driver Development
April 2001
DeveloperNet University Course

Lab 1: Installing the Basic Lab Driver


Module Objective: During this lab, you'll use the contents of the Lab1Driver folder on your desktop to install and configure the course's basic lab driver.

Important Note: If you haven't done so already, download the course folder to your development machine at this time.

Preparation Steps:

  1. Launch eDirectory from the NT Services console (shown in Figure 1) obtained by double-clicking "Services" in the Control Panel. Set its "Startup" to "Manual" so that it will not start automatically every time you boot the system. This will make it easier to find some configuration problems. Each time you launch eDirectory, an NT Server Control Activity Indicator will display until the launch is complete.



    2. Figure 1: NT Services Console (launched from the Control Panel)


  2. Wait until the NT Server Control Activity Indicator disappears. Then login to eDirectory using the password you assigned to your admin object when you installed eDirectory.


    3. Server Conrol Activity Indicator


  3. Double-click c:\Novell\NDS\NDSCons.exe to launch eDirectory Console as shown in Figure 2.



    4. Figure 2: eDirectory Console (launched from NT Services Console)

  4. The TESTTREE tree name and SERVERNAME server object name used in the following labs may be different than the name of the NDS tree and server object at your workstation. To determine your server and tree name, look at the NDS Server Console that was displayed when you started eDirectory. Figure 2 shows you how to determine the appropriate server and tree names. Substitute the appropriate server and tree names for all of the procedures in this lab series.


  5. The following procedures refer to drive letter 'C:' for file locations. Your workstation's main drive letter may be different. Use the appropriate drive letter for your workstation.


  6. All names in the following procedures are case-sensitive.


  7. As a convenience, set "NDS Server" (eDirectory) to Manual so that it does not automatically start up every time you reboot.

Main Procedure

Notes:

  1. In the following steps, you'll add objects to the lab tree as shown in Figure 3.


  2. For the remainder of these labs, the Organization object that contains your eDirectory server object will be referred to as "Novell".


Figure 3: The Lab Tree


The procedure below will guide you through the process of installing and configuring all of the objects needed to get the lab 1 version of the PBXSimulator driver up and running. The steps described make all of the links manually as opposed to using a wizard. This is done intentionally to acquaint you with the inner-connections in a DirXML driver configuration.


Create an NDS XMLDriver DriverSet using ConsoleOne.

  • Start the TESTTREE lab tree on your machine.

EXPLANATION: If eDirectory is not currently running, display the Control Panel and launch the "Services" control. From "Services," launch eDirectory. Then, use the NetWare log in utility (accessable from the Start menu) to immediately login.

  • Launch the DirXML extended version of ConsoleOne (often located at c:\nds\ConsoleOne\bin\ConsoleOne.exe).

Note: In the following steps, you'll add objects to the lab tree as shown in Figure 3.

  • Create a DirXML-DriverSet object inside of the Organization object that contains your server object that represents your eDirectory server.

Note: For the remainder of these labs, the Organization object that contains your eDirectory server object will be referred to as "Novell".

EXPLANATION: Right-mouse-click over the "Novell" object and select "New>Object." Use the resulting "New Object" dialog to create a "DirXML- DriverSet" class of object. Name the new object "MyDriverSet."

DirXML-DriverSets are containers. In the following steps you will create the objects used to contain information about a particular DirXML-Driver inside of the MyDriverSet object.

  • Create a DirXML-Driver named "Lab1Driver" inside of the "MyDriverSet" object.

EXPLANATION: Right-mouse-click over the "MyDriverSet" object and select "New>Object." Use the resulting "New Object" dialog to create a "DirXML-Driver" class of object. Name the new object "Lab1Driver."

Note: If a dialog similar to this one appears, ignore it. Later steps resolve these issues.

  • Create the following 3 objects inside of the "Lab1Driver:"
    • DirXML-Publisher named "Lab1Publisher"
    • DirXML-Subscriber named "Lab1Subscriber"
    • DirXML-Rule named "Lab1MappingRule" (Schema Mapper)

EXPLANATION: DirXML-Driver objects are containers that are intended to contain other objects that describe a particular DirXML-Driver.

  • Create the following 2 objects inside of the "Lab1Publisher:"
    • DirXML-Rule named "Lab1PubCreate" (Create Rule)
    • DirXML-Rule named "Lab1PubPlacement" (Placement Rule)


  • Create the following 3 objects inside of the "Lab1Subscriber:"
    • DirXML-Rule named "Lab1SubMatching" (Matching Rule)
    • DirXML-Rule named "Lab1SubCreate" (Create Rule)
    • DirXML-Rule named "Lab1SubPlacement" (Placement Rule)


  • Create OUs to contain the lab's User objects as shown in Figure 3.
    • Create two OUs inside of organization Novell, named "Orem" and "Provo."
    • Create two OUs inside of "Orem," named "Engineering" and "Finance."
    • Create two OUs inside of "Provo," named "Engineering" and "Education."

Note: You will reuse the OUs you created in this step in all labs. So, only do this step once and then ignore it for all subsequent labs.

2. Build the shim executables that implement the DirXML shim interfaces for the Lab1 driver.

Important Notes (Read Carefully)

Before performing the steps below, you must make the following changes to the "C:\DirXMLCrsFldr\Lab1Driver\sources\Lab1DriverShim.java" file:

  1. If your labs are installed on a drive other than "C:," you must change the reference to "C:" in "Lab1DriverShim.java" to the correct drive letter before you build.


  2. If your tree name is not "TESTTREE," you must change the reference to "TESTTREE" in "Lab1DriverShim.java" to the appropriate tree name before you build.


  3. Every time you change a .JAR file (recompile), YOU MUST SHUT DOWN AND RESTART EDIRECTORY. This is because the Java Virtual Machine caches all classes at start-up. If you don't restart, your new .JAR files will never be loaded.

    1. Open each of the following three .java files in "C:\DirXMLCrsFldr\Lab1Driver\sources\ " directory with Notepad and examine them. Set the font to Courier (a non-proportional font) so that things line up properly.


      • Lab1DriverShim.java
      • Lab1PublicationShim.java
      • Lab1SubscriptionShim.java


    2. As you see, each implement an interface for a shim required by the DirXML driver (a driver implementation shim, a Publisher implementation shim, and a Subscriber implementation shim). The interface classes for these shims are located in "C:\DirXMLCrsFldr\Lab1Driver\sources\vrd.jar."


  4. Open a Command window (equivalent to the DOS window on Windows 98) and cd to "C:\DirXMLCrsFldr\Lab1Driver\sources\."

  5. Type "build" in the DOS window to execute the build.bat file in the "sources" directory. A file named "Lab1Driver.jar" will be created in the "sources" directory. This .jar file contains the shim classes compiled from the java sources you viewed earlier.

  6. Copy the Lab1Driver.jar file to the "C:\Novell\NDS\lib" directory on your machine. eDirectory was installed in the "C:\Novell\NDS\" directory.

  7. Copy the pbx.jar file from your course directory to the "C:\Novell\NDS\lib" directory on your machine. This JAR file contains the classes for the PBXSimulator application and must be located in the Lib directory so that the lab driver can load it.

  8. Copy the swing.jar file from your course directory "c:\DirXMLCrsFldr" to the "C:\Novell\NDS\lib" directory on your machine. This JAR file contains the Java classes for the GUI in the PBXSimulator application and must be located in the Lib directory so that PBXSimulator can load it.

3. Configure NDS objects inside of "Lab1Driver" to fully define the Lab1 DirXML-Driver.


Important Notes (Read Carefully)

  1. In the following steps, you will be asked to copy the contents of .xml and .xsl files into DirXML NDS objects. Don't open the source files in a browser. Use Notepad or a similar application instead. Copied text from a browser window will include invisible characters that interfere with DirXML's ability to parse the information.


  2. Completely delete all existing text from each NDS object before copying xml\xsl source data into it.


  3. If the tree name on your workstation is not TESTTREE, then you will need to change all references to TESTTREE in pubPlacementRule.xml to refer to the correct tree.


  4. In the following step, as you create and populate the mapping rule, the dialog below may appear. Ignore the dialog if it appears.




  5. In ConsoleOne, open properties for each of the object’s listed below. Then click the down arrow in its “DirXML” tab and select “Edit XML” to display each edit field for copy. Use NotePad to copy the text from the appropriate file into the ConsoleOne edit field. After each copy, click "Apply" to commit the new data.

    • MappingRule.xml -> Lab1MappingRule.Lab1Driver
    • pubPlacementRule.xml -> Lab1PubPlacement.Lab1Publisher.Lab1Driver
    • pubCreateRule.xml -> Lab1PubCreate.Lab1Publisher.Lab1Driver
    • subMatchingRule.xml -> Lab1SubMatching.Lab1Subscriber.Lab1Driver
    • subCreateRule.xml -> Lab1SubCreate.Lab1Subscriber.Lab1Driver
    • subPlacementRules.xml -> Lab1SubPlacement.Lab1Subscriber.Lab1Driver


Note: In the following step, you will add and edit attributes using ConsoleOne's "Other" properties page. As you do so, the page's "Add" button will disable. To re-enable the "Add" button, click on the attribute list title that reads "Attributes:" at the top of the page.

    1. Inspect the NDS objects defining the Lab1 DirXML-Driver to verify that they are correctly associated with each other.
      1. Using the Lab1Driver DirXML-Driver object's "Other" properties page, verify the following object reference attributes and browse to set their values as shown below if necessary:
        2. ATTRIBUTE TYPE VALUE
        DirXML-MappingRule Lab1MappingRule.Lab1Driver.MyDriverSet.Novell

        Click "Apply" and then "Close" to commit your additions.



      2. Using the Lab1Publisher.Lab1Driver object's "Other" properties page, verify the following attributes and browse to set their values as shown below if necessary:
        3. ATTRIBUTE TYPE VALUE
        DirXML-CreateRule Lab1PubCreate.Lab1Publisher.Lab1Driver.MyDriverSet.Novell
        DirXML-PlacementRule Lab1PubPlacement.Lab1Publisher.Lab1Driver.MyDriverSet.Novell

        Click "Apply" and then "Close" to commit your additions.



      3. Using the Lab1Subscriber.Lab1Driver object's "Other" properties page, verify the following object reference attribute and browse to set its value as shown below if necessary:
        4. ATTRIBUTE TYPE VALUE
        DirXML-MatchingRule
        		 Lab1SubMatching.Lab1Subscriber.Lab1Driver.MyDriverSet.Novell
        DirXML-CreateRule
        		 Lab1SubCreate.Lab1Subscriber.Lab1Driver.MyDriverSet.Novell
        DirXML-PlacementRule
        		 Lab1SubPlacement.Lab1Subscriber.Lab1Driver.MyDriverSet.Novell

        Click "Apply" and then "Close" to commit your additions.



    1. Add the Server object to the DirXML-DriverSet.

      1. Select and hold the "MyDriverSet" NDS object's "DirXML" properties page tab until a drop-down-menu appears. Select "Server" in the menu to display the driver set's Server page as shown in Figure 4.


      2. Select "Add" to browse for the NDS Server object's you are using.


      3. Click "Apply" and then "Close" to commit your changes.



      Figure 4: The Driver Set's Server Page.


    1. Select the security proxy for your driver objects.


      1. Select the "Lab1Driver" NDS object's "Memberships" properties page tab as shown in Figure 5





        2. Figure 5: Lab1Driver's Membership Properties Page


      2. Select "Add" to browse and select "Admin.Novell."


      3. Click "Apply" and then "Close" to commit your changes.


    1. Associate the Lab1 driver's shim class with the "Lab1Driver" NDS object.


      1. Select and hold the "Lab1Driver" NDS object's "DirXML" properties page tab until a menu appears. Select "Driver Configuration" in the menu as shown in Figure 6.


        2. Figure 6: Lab1Driver's Property Page


      2. Select "Java" for executable type.


      3. Type the case sensitive name of the class implementing the driver shim, "Lab1DriverShim." Do not enter the ".class" suffix of the name. This class is located in the Lab1Driver.jar file you put in the c:\Novell\NDS\Lib directory.


      4. Click "Apply" and then "Close" to commit your changes.


    1. Define the filter sets to be used by the Lab1 driver.


      2. EXPLANATION:The filter sets define the class and attribute types that are allowed to pass.

      Notice that there are three that you need to be concerned with:


      1. The server filter defines the objects that will be maintained in the filtered replica.


      2. The Publisher filter defines the object and attribute types that can be published to the NDS tree. The XDS that is produced after all of the transforms and rules are applied to the inputted Publisher document, must only refer to object and attribute types defined in the Publisher filter. If a filtered replica is used for the driver, the object and attribute types in the Publisher filter must be a subset of the server filter.


      3. The Subscriber filter can be completely different from the Publisher filter because you may be pushing completely different objects and attributes out from NDS to the external system than you are receiving from it. However, if a filtered replica is used, the Subscriber's object and attribute types must also be a subset of the server filter.


    1. Select the Server object you will use with your DirXML driver and display its properties page. Click and hold the downward-pointing arrow on the "DirXML" properties page tab until a menu appears. Select "Filter" in the menu.


    2. Click "Edit Filter" in the page to display a class and attribute selection dialog. Select "User" class with the following attributes:
      • CN
      • Given Name
      • L
      • Object Class
      • OU
      • Surname
      • Telephone Number
      • Title
    1. Click "OK" to close the "Edit" window. Then click "Apply" and then "Close" to commit your changes.


    2. Open the "Filter" property page in Lab1Publisher.Lab1Driver.MyDriverSet.Novell." Click "Edit Filter" and select "User" class and add the filter attributes below. Click "OK" to close the "Edit" window. Then click "Apply" and then "Close" to commit your changes.


      • CN
      • Given Name
      • L
      • Object Class
      • OU
      • Surname
      • Telephone Number
      • Title
    1. Open the "Filter" property page in "Lab1Subscriber.Lab1Driver.MyDriverSet.Novell." Click "Edit Filter" and select "User" class and add the filter attributes below. Click "OK" to close the "Edit" window. Then click "Apply" to commit your changes.
      • Given Name
      • Surname
      • Telephone Number
      • Title
    1. Still in the "Filter" property page in "Lab1Subscriber" Click "Edit Filter" again and select the "Organizational Unit" class to add the "Object Class" attribute to it. Click "Apply" and then "Close" to commit your change.


    1. Configure the Lab1 driver for "Manual" start.


      1. Click and hold the downward-pointing arrow on the Driver Set object's "DirXML" properties page tab until a menu appears. Select "Drivers" in the menu to display a dialog similar to the one shown in Figure 7.



        2. Figure 7: MyDriverSet's Property Page


      2. Select "Lab1Driver.Novell " object in ConsoleOne and click "Properties" to display the DirXML, Driver Configuration property page of the "Lab1Driver" NDS object similar to that shown in Figure 8.



        3. Figure 8: DirXML Properties


      3. Select "Startup Option" as the type of property you want to modify.


      4. In the resulting dialog, select "Manual."


      5. Click "Apply" and then "Close" to commit your changes.


      6. Click "Cancel" to close "Properties of MyDriverSet."



    4. Display DSTrace for DirXML to view status logs from the Lab1 driver.

    EXPLANATION: We want to start up DSTrace before we start the driver because there may be critical status logs that occur on start-up that will help us troubleshoot any problems that occur.

    1. At the eDirectory console, select DSTrace (shown below) and click "Start." The DSTrace window should appear.


      Figure 9: eDirectory Console



    2. In the DSTrace window, select Edit>Options to view the available logging sources.


    3. In the DSTrace>Options window, click the "Clear All" button to clear all of the default logging sources. Then, click "DirXML Drivers" to limit the logs displayed in the DSTrace window to the "DirXML Driver" source.


    4. Click OK in the DSTrace>Options window to commit your selection and close it.


    5. Start the Lab1 DirXML driver.

    EXPLANATION: On start-up, all configured rules files and style-sheets are read from their respective objects in NDS and cached. This is done to optimize transaction speed.

    If you make a change to shim code, a rule file, or a style-sheet, you must shut down eDirectory and restart in order to have the change take effect.

    1. To set up your driver to print useful error messages to DSTrace, display the DirXML-DriverSet object's "Other" properties and add a new attribute:
      DirXML-DriverTraceLevel and set its value to 4.


    2. Click and hold the downward-pointing arrow on the DriverSet object's "DirXML" properties page tab until a menu appears. Select "Drivers" in the menu.


    3. Select the "Lab1Driver" in the driver set and then click the "Start" button. Many entries should suddenly be logged in the DSTrace window. Among them, the following line should appear:
      Lab1DriverShim.init

    PBXSimulator Notes (Read Carefully)

    1. Always remember to double-click list items int the PBXSimiluator application to select them as shown in Figure:10.


      2. Figure 10: PBXSimulator GUI


    2. The "modify" operation will be added to the publisher and subscriber in later labs and so will not work at this point.


    3. The "modify" operation will be added to the publisher and subscriber in later labs and so will not work at this point.


    4. The lab driver will poll PBXSimulator every 4 seconds and print a trace similar to the following in the DSTrace window:PBXAccountPanel.getDBEvents() called


    5. The following steps will have you create objects on the PBXSimulator side or the NDS side and have corresponding objects created on the other side by the lab driver. The ability to push modifications (attribute value changes) made to an object on one side to the other side will be added by you during later programming labs.


    6. When accounts are created on the PBXSimulator side, you must select "Refresh" om ConsoleOnes's "View" menu to have ConsoleOne's display updated so that you can see the new object.


    7. If you copy a .JAR file into c:\Novell\NDS\Lib, you must shut down eDirectory and restart in order to have the change take effect.


    8. Ise DSTrace to help you troublshoot. Create a new trace for each operation so that you won't get confused when reading output.



    9. Attempt to create an account in PBXSimulator. Fill in values for all fields.


      10. Important: Always click PBXSimulator's "Commit" button to commit PBXSimulator events to the driver. If the publisher operates successfully, a corresponding User object will be created in the NDS tree.


    10. Attempt to create a User object in "Engineering.Provo.Novell" of the NDS tree.

      Click Apply in the User object's property pages. If the subscriber operates successfully, a corresponding account will be created in PBXSimulator.

      Any phone numbers, given names, or titles that you may have entered in the NDS User will not be sent to PBXSimulator because the "Define additional properties" page information causes modify operations and modify has not been implemented yet.

    11. Attempt to create an Organizational Unit named "San Jose" inside of the "Novell" organization. If the subscriber operates successfully, PBXSimulator's "Edit Locations" window should display the new location.

    12. Attempt to create an Organizational Unit named "Engineering" inside of the "San Jose" organization. If the subscriber operates successfully, PBXSimulator's "Edit Locations" window should display the new department.


    Previous Contents Next
    download sample file