Importing Java packages and other custom code

Map Designer Express provides two ways to import Java packages and other custom code:

A description of each method follows.

Importing Jar libraries as activity function blocks

In addition to using the standard function blocks that Activity Editor provides, Map Designer Express allows you to import your own Java library for use as function blocks in Activity Editor. Importing custom Jar libraries into activity settings will enable any public methods in the Jar library to be used as function blocks in Activity Editor.

Steps for importing Jar libraries as activity function blocks

Before you begin: You need to export your Java classes into a .jar file.

Perform the following steps to import a Jar library into Activity Editor:

  1. In System Manager, open the Activity Settings view by clicking Window > Show View > Other and selecting Activity Settings from the category System Manager.
  2. Right-click BuildBlock Libraries and select Add Library. Figure 85 shows the Activity Settings view for adding a custom Jar library.
    This figure shows the Activity Settings screen with the Add Library option highlighted.
    Figure 85. Activity Settings view
  3. In the Open File dialog box, navigate to your custom .jar files and select Open.

    System Manager will try to import your custom .jar file for use as function blocks in Activity Editor. If the file is imported properly, the name of your custom .jar file will appear under BuildBlock Libraries in the Activity Settings view.

    Tip: After you import your custom .jar files into Activity Settings, when your maps and collaboration template compile in System Manager, the custom .jar file will automatically be included into the compile CLASSPATH. To prepare InterChange Server Express for compilation, make sure that its CLASSPATH includes your custom.jar file. For information on setting up InterChange Server Express for importing your custom .jar files, see Importing third-party classes to InterChange Server Express.

  4. Restart Map Designer Express.

    Rule: After you change any settings in the Activity Settings view, you must restart Map Designer Express for the change to take effect in Activity Editor.

Result: When you open Activity Editor, the custom Jar library will be listed in the Library window under My Library in Activity Editor. By default, available custom function blocks are listed according to their package structure. You can use them in an activity the same way as standard function blocks.

Customizing display settings of custom Jar libraries

You can customize the display settings of the function blocks imported into Activity Editor, such as its name and icon, by changing the custom Jar library's properties. Perform the following steps to do this:

For the Java package and classes, you can customize the display name of the entry and whether Activity Editor should display this Java package/class in the My Library tree structure by changing the check box "Hide level in tree display." If this option is enabled, Activity Editor will not display this entry in the My Library subtree. This option is usually useful when the Java methods in your custom Jar library are in a Java class that is in a package many levels deep, and enabling this option can better organize your My Library subtree in Activity Editor.

Figure 86 shows the dialog for customizing the Jar library display.

Figure 86. Properties dialog for customizing Jar library display

For those Java methods used as function blocks in Activity Editor, you can specify the function block display name, description, icon, and parameter's display name in the Properties window. When you import an icon for the function block, the icon that you select will be copied into the Activity Settings folder and will be available for other function blocks in the same package to use.

Recommendation: If you choose to import an icon for your function block to use, the icon should be 32 pixels by 32 pixels in size and should be in .bmp format. The color depth of the icon can be up to 24-bit.

Figure 87 shows the Properties dialog for customizing the Jar library function block display.

Figure 87. Properties dialog for customizing Jar library function block display

Rule: After you change any settings in the Activity Settings view, you must restart Map Designer Express for the change to take effect in Activity Editor.

Note:
You can import and export activity settings using the Import/Export wizard in the Eclipse Workbench. For more information, see the documentation for the Eclipse Workbench.

Importing through the Map Properties dialog

Map Designer Express automatically imports the Java packages necessary to execute a map. If you write transformation code that uses methods from another Java package, or if you use the Map Utilities (MapUtils) package, you need to import the package into the map. You can also write your own custom Java code outside of Map Designer Express and import your code into a map for use within transformation code.

Note:
The version of the Java Development Kit (JDK) that is appropriate for the IBM WebSphere Business Integration Server Express release must be installed for map development.

Attention:
Map Designer Express cannot debug or verify the logic of any code imported into a map. Consequently, the map developer is responsible for all errors and exceptions caused by imported code.

Steps for importing Java packages or other custom code

To import a Java package or other custom code:

  1. Display the General tab of the Map Properties dialog, as follows:

    From the Edit menu, select Map Properties. For information on other ways to display the Map Properties dialog, see Specifying map property information. The Map Properties dialog box appears (see Figure 92).

  2. Enter the import statements in the Map file declaration block. You can also enter other Java statements in the Map local declaration block.
    Note:
    When you compile the map, the Java compiler looks for imported packages in the directory defined by the CLASSPATH environment variable. If you import a package into a map and deploy the map at another InterChange Server Express system before compiling it, make sure you also deliver the imported package with the map.

    For requirements for compiling a map with System Manager, see Compiling a map.

    All statements execute at the beginning of the map, before any transformation steps execute.

  3. Click OK to close the Map Properties dialog box.

Steps for importing map utilities

To use the Map Utilities package, you must import it into the map by performing the following steps:

  1. Ensure the CollabUtils.jar file is in the <ProductDir>\lib directory.
  2. Ensure the start_server.bat (or CWSharedEnv.sh) file contains a reference to the CollabUtils.jar file.
    Note:
    Steps 1 and 2 are needed for the server compile.
  3. Modify the Compiler Classpath preference for compiling the maps and collaboration templates from System Manager:
    1. In System Manager, select Window > Preferences to open the Preference dialog.
    2. Expand System Manager Preferences, and select Compiler.
    3. In the Compiler preference page, click New and select the .jar file to be included in the compile CLASSPATH for maps and collaboration templates.
  4. From Map Designer Express, open the map that needs to use the Map Utilities package.
  5. Display the Map Properties dialog.
  6. In the Map Properties dialog box, type the following import statement in the Map file declaration block:
    import com.crossworlds.MapUtils.*;
  7. Click OK to close the Map Properties dialog box.

Importing third-party classes to InterChange Server Express

If the imported classes are in a third-party package rather than in the JDK, in order to set up the server compile, you must add them to the path of the imported classes in the JCLASSES variable.

Recommendation: You should use some mechanism to differentiate those classes in JCLASSES that are standard from those that are custom.

Example: You can create a new variable to hold only those custom classes and append this new variable to JCLASSES, by performing the following steps:

  1. Create a new map property, such as one called DEPENDENCIES.
  2. Place the CwMacroUtils.jar in its own directory.

    Example: Create a dependencies directory below the product directory and place the jar file in it.

  3. Add the dependencies directory to the file used to start InterChange Server Express (by default, start_server.bat or CWSharedEnv.sh), which is located in the bin directory below the product directory. For example, add the following entry for Linux:
    set DEPENDENCIES=$ProductDir/
    dependencies/CwMacroUtils.jar

    Add the following entry for Windows:

    set DEPENDENCIES="%ProductDir%"\dependencies\
    CwMacroUtils.jar
  4. Add DEPENDENCIES to the JCLASSES entry:

    For Linux, add:

    set JCLASSES=$JCLASSES:ExistingJarFiles:
    $DEPENDENCIES

    For Windows, add:

    set JCLASSES=ExistingJarFiles
    ;%DEPENDENCIES%
  5. In each map that uses the classes, include the PackageName.ClassName specified in the CwMacroUtils.jar file.
  6. Restart InterChange Server Express to make the methods available to the maps.

Note:
Be sure you have modified the Compiler Classpath preference for compiling the maps and collaboration templates from System Manager. To do this, perform the following steps:
  1. In System Manager, select Window > Preferences to open the Preference dialog.
  2. Expand System Manager Preferences, and select Compiler.
  3. In the Compiler preference page, click New and select the .jar file to be included in the compile CLASSPATH for maps and collaboration templates.

Guidelines: When importing a custom class, you may get an error message indicating that the software could not find the custom class. If this occurs, check the following:

Example: When importing a custom class, you might create a folder called %ProductDir%\lib\com\<ProductDir>\package, where package is the name of your package. Then, place your custom class file under the folder you just created. Finally, in the CLASSPATH variable in the start_server.bat file, include the path %ProductDir%\lib.

Copyright IBM Corp. 2004, 2005