Getting Started

To create a new transform, you must:

  1. Get a working Comparator development environment
  2. Define the transform's function and interface
  3. Write the transform
  4. Add the transform to the Comparator

After completing these steps, you will be able to use your transform in the Comparator.

Designing a New Transform

Start by deciding what your transform should do. You need to consider how your transform will handle unexpected conditions or erroneous input. Identify the information your transform needs. Determine what comes from the previous transform, what comes from the user, and what is obtained programmatically.

Pick a name for your transform. A recommended name is a concise description of what your transform does followed by the word Transform. Prevailing style is to use names that are mixed case, start with a capital letter, and capitalize the first letter of each interior word. The name must be a valid class identifier in Java and must not be the same as any of the existing class names in the Comparator. TRANSFORM will indicate the name of your transform for the rest of this document.

If your transform is going to have a user interface, sketch it out before building the transform. Most simple interfaces are layed out on grids and have the appearance of forms.

Writing a New Transform

There are three ways to start writing a transform. The easiest and recommended method is to start with one of the provided transform templates. This method will be the one described in these instructions. Once you are comfortable with writing transforms, it may be easier to subclass Transform or an existing transform rather than starting from the template. This is how all of the transforms included with the Comparator were written. It is also possible to implement the ITransform interface directly although this would require a lot of work.

You should take the time to read over the documentation for the IDataElement and IEditableDataElement interfaces as well as this overview of data elements before attempting to write a transform.

  1. Copy TransformTemplate.java in BASE/jigcell/compare/contrib to TRANSFORM.java.
  2. Open TRANSFORM.java in a text editor.
  3. Replace A DESCRIPTION OF YOUR CLASS in the class documentation with a few sentences that describe what your transform does.
  4. Replace YOUR NAME HERE on the author line of the class documentation with your name.
  5. Replace all uses of TransformTemplate with TRANSFORM. You should see /* CLASS NAME */ around each usage to make it stand out. There should be three places where this is done.
  6. The DISPLAY INFORMATION block defines information about your transform that will be visible in the Comparator. The NAME_TRANSFORM variable should be set to the display name of your transform. Unlike the class name, the display name can contain spaces and should be formatted like a title. The DESCRIPTION_INPUT and DESCRIPTION_OUTPUT variables will be displayed when the user requests information about what input and output types your transform supports. You can also use this space to describe what your transform does. The input and output descriptions may use HTML 3.2 tags to format the text. Descriptions for the transforms included with the Comparator are in the BASE/jigcell/compare/transform/resource/help directory.
  7. Add the code to perform your transform under /* CODE TO PERFORM COMPUTATION */. An IDataElement called input provides input to the transform and an IEditableDataElement called output takes output from the transform.

If your transform encounters an error, it is best to handle the error and recover from it. Although the Comparator attempts to clean up transforms that fail, it is not always successful. Your transform should trap exceptions during evaluation and return cleanly. If a fatal exception occurs in your transform, you can report that to the Comparator using the fireEvaluationError(Exception) method. If you have detected a fatal condition in your transform but did not catch an exception, you can still report an error message using the fireEvaluationError(String) method. Using these methods allows the Comparator to report errors in your transform to the user.

Optional Tasks

The only code you must provide for a transform is to perform the computation. The transform template also provides stubs for creating an interface for your transform and providing annotation information.

There are two ways to add a graphical interface to your transform. Using the template, add code under /* CODE TO CREATE INTERFACE */. Place your interface components in the provided JPanel called panel. You can also create an implementation of ICustomizableInterface. If you subclassed Transform instead of using the template, this is the preferred way to create an interface. The setInterfaceClass method indicates the name of the ICustomizableInterface class that your transform uses. If you do not provide an interface, an empty one will be created for you by default.

The transform annotation provides programmatic information about your transform. The Comparator does not require your transform to have annotation information. If you want your transform to support this, add code to create the annotation under /* CODE TO UPDATE ANNOTATION */. An ITransformAnnotation called input allows you to inspect the annotation of the previous transform. Write to the TransformAnnotation called output.

Adding a Transform to JigCell

  1. Save TRANSFORM.java.
  2. Compile your transform by running make in BASE. If make reports errors, correct them in the source code and run make again. You cannot proceed until all of the errors in your transform have been fixed.
  3. Open BASE/www/installer/shared/compare.config in a text editor.
  4. Scroll to the line starting with <string>jigcell.compare.transform.SelectColumnsTransform,. Insert ,jigcell.compare.contrib.TRANSFORM after the last transform and before the </string>.
  5. Save compare.config.
  6. Run make distro in BASE to generate an installer containing your transform. The installer will be located in BASE/www. This installer is used the same way as the normal JigCell installer.