Creating your extension on the IBM Director Server


Use these steps to create and test your extension:

  1. Install Eclipse.
  2. Create a new Java project.
  3. Create the extension class.
  4. Create a folder structure for deploying the extension.
  5. Tell IBM Director how to find your class with a .TWGExt file.
  6. Override a couple of methods in the extension class.
  7. Create a JAR file.
  8. Deploy the code onto the IBM Director Server.
  9. Turn on output logging so that you can see messages.
  10. Restart the IBM Director Server.
  11. Check the log files for your start messages.
  12. Check the IBM Director Console to find your extension.
  13. Stop the IBM Director Server.
  14. Check the log files for your start messages.


Start Eclipse

If you have not alread done so, install Eclipse.

Note: This description was done with Eclipse 3.0.

Create a new Java project

Start by creating a new Java project in Eclipse. Use the File->New>Project.. menu.

This will bring up the New Project dialog. Select Java->Java Project then click Next

Now enter the project name - for our example, this is BobCo.
Select "create separate source adn output folders.

Now select Finish.

The project will appear at the upper left in Eclipse. Now right-click the project and select Properties. We need to add the appropriate IBM Director jars to the project so click on the Java Build Path then select add external jars. Use the file chooser to select both IBM Director.jar and DirLibs.jar. Click Open.

Now go back to the Order and Export tab move the IBM Director jars to precede the JRE in the build path.

Create the extension class

Now it's time to start programming! Right-click the src folder and select New->Package. Enter the package name. In our sample, the package name is "com.bobco"

Now create a class to hold the extension code. Right-click the com.bobco package and select New->Class

This is the main class for for our extension. This class will run first.

Again, the basic idea is this:

  1. Create an extension class and tell IBM Director the location of the extension class
  2. IBM Director will call your code. There are two important fields to enter:
    1. Enter a class name for the extension
    2. Enter the super class. This must be com.tivoli.twg.engine.TWGExtension.
  3. Click Finish.

Create an image to deploy

The next step is to create a directory structure in the project that will match the directory structure of your extension when it is deployed onto IBM Director.

  1. Right-click the project and select New->Folder
  2. Enter the file name "deploy".
  3. Right-click the "deploy" directory and select New->Folder.
  4. Enter the file name "classes".
  5. Right-click the "classes" directory and select New->Folder.
  6. Enter the file name "extensions".

Tell IBM Director how to find your class

Now that you have an extension class, you must tell the IBM Director server how to find that class. A special file called an "Extension file" is used to give IBM Director the location of the extension class. The file name must always end in ".TWGExt".

  1. Right-click the extensions directory and select New->File.

  2. Enter the filename.
  3. Ensure that the file extension is .TWGExt
  4. Click Finish.
  5. Now you need fill in the Extension file. This file in the format of a Java Properties file. Extension files can have many different properties in them, but to start your extension, we need only these properties:

    classpath.append.1
    This tells IBM Director where to look for your extension class. Set it to the name of your jar file and tell it that your jar file will be in the IBM Director classes directory
    twg.extension.classname
    This tells IBM Director the name of the class that extends TWGExtension.

    The following fields allow IBM Director to display your extension's information in it's Help->Product Info menu on the IBM Director Console.

    twg.extension.name
    This the name of your product.
    twg.extension.vendor
    Your company name.
    twg.extension.version
    The version of the extension.

    NOTE: IBM Director is an internationalized product. Later, you will see how to display product information with strings that are translated to fit the Locale of the IBM Director Console.

    The first Extension file will look like this:

    Override a couple of methods in your extension

    Now that you have created the extension file to point the IBM Director Server to the extension class, you need to add the code.

    There are many methods in TWGExtension that you can override but, for now, you only need the following two:

    1. InitClassInstances() is a method that IBM Director will call when the IBM Director Server starts. The InitClassInstances() method gives your extension a chance to initialize itself.
    2. TermBegin() is a method that the IBM Director Server will call when the IBM Director Server is about to stop. The TemBegin() method will allow your extension to terminate gracefully. Things you might want to do in this method include:
      • Close open files
      • Close socket connections

    Right-click inside the extension class and select Source->Override/Implement Methods.

    Now check the two methods of override and click OK.

    Now edit the code. For now, just put print statements inside each one. When you have finished the code and cleaned up the comments, it will look like this:

    Create a JAR file

    Create a jar file containing all of the code for the extension. Use the File->Export menu to create a jar file to hold all the code for our extension. Ensure that the jar file name matches what is in the classpath.append line in the Extension file.
    Find the "classes" directory in your workspace and save the JAR file there.

    Deploy the code onto IBM Director

    To deploy your simple extension, there are two files that must be copied into IBM Director Server IBM Directories.

    1. Copy the .TWGExt Extension File to the IBM Director classes\extensions directory
    2. Copy the Jar file to the IBM Director classes directory.

    Once you ship your Jar, you will need to write an install procedure to perform the file copies into the appropriate places in the IBM Director file structure.
    For now, we will deploy by exporting the contents of the "deploy" directory into the directory where IBM Director was installed:

    Right-click the "classes" folder and select Export. Choose to export to a filesystem.

    Select the directory where you installed IBM Director and click Finish.


    Tell IBM Director to save the STDOUT messages

    You must set a flag in IBM Director to cause your System.out.intln() statements to be written to a log file. Click Here for directions.

    Restart the IBM Director Server

    The Extension file is only read when the IBM Director Server restarts, so stop and restart the IBM Director server with these commands:

    What if something goes wrong?

    If something goes wrong when you are restarting the IBM Director Server or you are verifying you Extension, click here for debug help

    Check the log files for your start messages

    Once the IBM Director Server is started, you can look for the print messages in the log files. Log files are located in the IBM Director log Directory. There wll be several files in this Directory. For now, all you care about is the file named com.tivoli.twg.engine.TWGServer.stdout
    This file contains all of the standard output for Java code running inside the IBM Director Server. So:

    1. Change to the IBM Director log Directory
    2. Run the command: notepad com.tivoli.twg.engine.TWGServer.stdout
    3. Search for the BobCo message from BobCoExtension.InitClassInstances()

    Check the IBM Director Console to Find your Extension

    Now check that your Extension is in the IBM Director Product Information window.

    1. Start the IBM Director Console and log in
    2. Use the menu Help->Product Info

    Stop the IBM Director Server

    Now stop the IBM Director server:

    Check the log files for your start messages

    Look for the second println message from the extension.

    1. Change to the IBM Director log Directory
    2. Run the command: notepad com.tivoli.twg.engine.TWGServer.stdout
    3. Search for the BobCo message from BobCoExtension.TermBegin()


    Now that the extension is created, you can start adding functionality to IBM Director. But first, take care of a couple of details. Let's look at National Language Support.