From Cerberus Helpdesk Wiki

(Some steps in these instructions assume a Unix-based development environment. For Windows you can use TortoiseSVN to access Subversion. Since Eclipse runs on most major platforms, the majority of the instructions will be platform agnostic.)

Contents 1 Requirements 2 Setting up the development environment 3 Creating your driver sub-project 4 Writing your export driver 5 Distributing your exporter 6 Running your exporter (from Eclipse) 7 Running your exporter (from the command-line) 8 Actually doing something useful

Requirements

• Eclipse (Ganymede) for Java
• Subversion

Setting up the development environment

• Create a new workspace directory on your local machine:

• Checkout the project source code from the repository:

• Open Eclipse and use the new workspace directory you just created.

  

• Close the 'Welcome' tab and choose File->Import. Select General->Existing Projects into Workspace.

  

• Provide your workspace directory as the root directory and import the four sub-projects from the list. Click Finish.

  

• At this point you should be able to create a Run Profile to launch the ImpEx tool. We don't expect it to do anything at this point.

  

• Choose 'Java Application'

  

• Set up the Run Profile

  

• Click 'Run'. If all goes well, you should see some console output telling you a configuration file was expected.

  

Creating your driver sub-project

You're now ready to create a new sub-project for your own driver.

• Right-click in the white space in the Navigation tab on the left. Choose New->Java Project.

  

• Name your project following the "_______Exporter" convention. The bundled exporters are Cerb2Exporter and Cerb3Exporter. Your project should be something like GmailExporter or KayakoExporter. Once named, click 'Finish'.

  

Writing your export driver

At the very minimum your exporter will need a 'Driver' class that is responsible for reading the configuration file provided by the user. Each exporter is completely free to define the possible options in its configuration file template. We'll cover this more in the following steps.

• Right-click on your project's src folder and add a new class.

  

• Choose a package hierarchy (namespace) based on your domain name and the exporter name. Package names are generally lowercase like "com.webgroupmedia.cerb4". Name your new class "Driver". Click "Finish".

  

• At this point you should have the skeleton of a Driver class ready for implementation:

• In order for your new driver to do anything useful, you need to define a new configuration file template that users can copy and configure. ImpEx will check the requested driver from the configuration file when the ImpEx is started and the user provides their desired configuration file as the first argument. That means the absolute barebones configuration file for your driver will look like:

• For convenience during development, you can create your configuration file template in the Cerb4-Impex/example-config/ directory. If you choose to share your finished driver with the Cerb4 community you'd want to create a page here on the wiki explaining your configuration options (like this). The options your driver allows will depend primarily on the source you're exporting data from -- if it uses a database, and so on. Go ahead and create a new configuration file template in the Cerb4-Impex/example-config/ directory now. Use the example 'exportDriver line above and set it to the fully-qualified name of the Driver class you created earlier.

  

• This barebones configuration file will allow a user to select an instance of your new driver for an export. Let's add an example configuration option named 'userName' (lines 4-5) to demonstrate how properties from the configuration file are read. You'll notice we've also added a property group called '[general]'. These groups are simply used for human readability; they aren't parsed or utilized programatically.

• The actual reading and parsing of the configuration file is handled by the ImpEx primary project. You can access configuration properties using the Configuration singleton. To do so, you'll need to add the main project to your exporter's build path. Right-click on your project and choose Build Path->Configure Build Path. Click the 'Projects' tab. Click the 'Add' button. Check 'Cerb4-Impex'. Click the 'OK' button.

  

• You should now be able to access Cerb4-Impex's public classes in your exporter's scope. This simulates in development what happens in real-world use when the main project loads your exporter's Driver from a JAR using a classloader. We'll also cover that in more detail in the following steps when we get to "distribution".

• Let's add some example code to your driver to demonstrate how configuration files work. Open your Driver.java file and add the following method inside the Driver class. When prompted to qualify the 'Configuration' class, choose 'com.cerb4.impex.Configuration'.

• You'll notice on line 3 we're requesting the 'userName' property from our configuration file through the Configuration singleton. The first argument provided to Configuration.get() is the property name. The second argument is the default value to use if the property isn't found (or is disabled).

• That should provide us with proof that your exporter is actually running when the ImpEx is invoked. Now we need to bundle your exporter as a JAR file so it can be shared like a plugin.

Distributing your exporter

Exporter drivers are distributed as JAR (Java ARchive) files -- which are essentially just ZIP files with a special manifest.

• Right-click on your exporter project and choose Export.

  

• Choose Java->JAR File. Click Next.

  

• You only need to export your class files. You can uncheck ".project" and ".classpath" on the right.

  

• Click 'Browse' to export the JAR file into the Cerb4-Impex/drivers directory. Click 'Save'. Click 'Finish'.

  

Running your exporter (from Eclipse)

• Now we can modify the Run Profile we created earlier to launch your new driver. Select 'Run Configurations' from the Run menu again.

  

• Right-click on our earlier Run Profile and select 'Duplicate'. Name it 'Cerb4 ImpEx (MyExporter)'. This allows you to quickly launch different exporter instances. Click the 'Arguments' tab and enter your configuration file as the first program argument. Remember that the paths are relative to the Cerb4-Impex project since it has our main class.

  

• Once done, click 'Run'. You should see your driver's "Hello" message from our example above. If not, double check your configuration file path.

  

Running your exporter (from the command-line)

• Most users won't be using ImpEx inside Eclipse. The Cerb4 project provides a binary distribution of the ImpEx tool that's ready to run. You'd provide your driver as a JAR file and a sample configuration file. Users would place your JAR file in their ImpEx 'drivers' directory and then run the tool using a copy of your configuration file as the first argument.

  

Actually doing something useful

Up to this point we've demonstrated how to create a new driver with its own configuration file and how to run it. Since your driver may read from any datasource, this should provide you with a clean starting point.

You can look at the code for Cerb2Exporter and Cerb3Exporter for examples of working with JDBC database queries and writing XML using Dom4J. You should use Dom4J to write your output XML since it's provided by the project already.

Any driver worth its disk space will need to write output files that can be read by Cerb4's import system. Here's a reference of the XML format for the currently supported import objects.