Setting up DXLMagic

DXLMagic requires a few steps to setup. It comes with a graphical installer for Windows and with full source code for customization to your needs.

DXLMagic is available on OpenNTF from the following Web page: http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/DXLMagic

An introduction to DXL is available on Slideshare from the following Web page: http://www.slideshare.net/NotesSensei/ad215-practical-magic-with-dxl

The tools is licensed under a Apache 2.0 licence and its source code is available for re-use and customization to specific needs.

Highlights code added to the original

Chapter 9. Analyzing customizations 145

9.5.1 Downloading DXLMagic

Open the following Web site and select the Releases tab:

http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/DXLMagic

Figure 9-7 Download of DXLMagic

Make sure you download the latest version. You either download the

DXLMagicWindowsInstaller.exe (for automatic installation on Windows) or DXLMagic.jar for manual installation on any operating system. You will need a free registration on OpenNTF to download. OpenNTF is an IBM-sponsored foundation that makes Opensource tools around Lotus products available.

DXLMagic is written in Java and will run on Windows, Linux and Apple Macintosh. For the internal working of DXLMagic we make use of XMLUnit. The Windows installer includes XMLUnit. For installation on Linux or Mac you will need to download it separately from its project location:

http://xmlunit.sourceforge.net/

Make sure you download the latest stable version. We have used XMLUnit 1.2 (June 2008), so the file is xmlunit-1.2.jar.

9.5.2 Configuring DXLMagic

For Windows we provide an installer file DXLMagicSetup.exe. Before you run it, make sure that you have the following prerequisites:

򐂰 Java 6.0 installed (you can install it from http://www.java.com/)

򐂰 Notes 8.5x client installed (you can use older version of the Notes client, but DXL will not be fully accurate, so items might be missing in your comparison).

When you run the installer, it will copy all the necessary jar files into the Notes client program directory and create a cmd file in your Windows Start menu. See Figure 9-8.

Figure 9-8 The DXL Magic Installer Welcome window

After you begin the installation, you will be prompted to confirm the location for the installation files, as shown in Figure 9-9.

Chapter 9. Analyzing customizations 147

We recommend that you follow the default recommendation of the installer which points to your Lotus Notes Client Java Client library directory. After the installation is complete, you will also find a menu entry under the Programs menu, as shown in Figure 9-10.

Figure 9-10 The completed installation creates a menu entry

9.5.3 Manually configuring DXLMagic

If you would like full control over what the installer is doing or you are running Mac OS/X or Linux, you will need to manually install DXLMagic.

Perform the following steps to manually configure DXLMagic:

1. Replace [AppDir] with the path to your Notes application (typically something like

C:\Notes, C:\Program Files\IBM\Lotus Notes, /applications/lotus/notes or

/opt/ibm/lotus/notes, depending on your platform.

2. Set [JarDir] where you copied the DXLMagic.jar and the [JarDir]/xmlunit-1.2.jar file.

Once you have completed these steps, perform these steps for configuring it: 1. Download Java 6.

2. Install and configure Java 6.

3. Copy the DXLMagic.jar and xmlunit-1.2.jar file into the [JarDir]

Note: It should work with Java 5 too, but this has not been specifically tested.

4. Edit your environment to include Notes on the path and the jar files on the classpath and add an environment parameter LD_LIBRARY:

– Windows: notepad c:\autoexec.bat and add these lines shown in Example 9-1.

Example 9-1 Editing your environment

SET PATH=%PATH%;[AppDir] SET

CLASSPATH=.;[AppDir]\jvm\lib\ext\*;[JarDir]\DXLMagic.jar;[JarDir]\xmlunit-1. 2.jar

SET LD_LIBRARY=[AppDir] (Reminder: if you have spaces in your path you need to put the path in quotes)

– Linux: sudo nano /etc/environment and add or edit these lines, as shown in Example 9-2.

Example 9-2 Editing the PATH and Classpath in a Linux environment

PATH="[whatever was there]:[AppDir]"

CLASSPATH=".:[AppDir]/jvm/lib/ext/*:[JarDir]/DXLMagic.jar:[JarDir]/xmlunit-1 .2.jar"

LD_LIBRARY="[AppDir]" DYLD_LIBRARY="[AppDir]"

– Mac: vi ~/.profile and add or edit these lines, as shown in Example 9-3

Example 9-3 Editing the PATH and Classpath in a Mac environment

export DYLD_LIBRARY_PATH=[AppDir]/Contents/MacOS (where AppDir is going to look something like: /Applications/Notes.app)

export

CLASSPATH=$CLASSPATH$:.:[AppDir]/Contents/MacOS/jvm/lib/ext/*:[JarDir]/DXLMa gic.jar:[JarDir]/xmlunit-1.2.jar"

Now we can proceed. Try the following command in a command window:

java com.ibm.sg.dxlmagic.DesignExporter

You should get a reply stating the required parameters for this command. If you get an error message either your path is not correct or you might need to reboot your machine.

Tip: When you copy the DXLMagic.jar and xmlunit-1.2.jar into the

[AppDir]/jbm/lib/ext you do not need to add these two explicitly to the CLASSPATH, because they are then covered by [AppDir]/jvm/lib/ext/*

Note: Depending on the size of your templates and your Java configuration, the DXLMagic

tools might run out of heap space. To avoid this, you can add a startup parameter to the Java command line:

java -Xmx1024m com.ibm.sg.dxlmagic.[NameOfTheTool]

Chapter 9. Analyzing customizations 149