Getting Started

To create a new objective function, you must:

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

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

Designing a New Objective Function

  1. Decide what your objective function should do. You need to consider how your objective function will handle unexpected conditions or erroneous input.
  2. Pick a name for your objective function. A recommended name is a concise description of what your objective function does followed by the word Objective. 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. OBJECTIVE will indicate the name of your objective function for the rest of this document.
  3. Identify the information your objective function needs. Determine what what type of data your objective function measures, what comes from the user, and what is obtained programmatically.
  4. Sketch out the user interface for your objective function. Most simple interfaces are layed out on grids and have the appearance of forms.

Creating a New Objective Function

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

You should take the time to read over the documentation for the IDataElement interface as well as this overview of data elements before attempting to write an objective function.

  1. Copy ObjectiveTemplate.java in BASE/jigcell/compare/contrib to OBJECTIVE.java.
  2. Open OBJECTIVE.java in a text editor.
  3. Replace A DESCRIPTION OF YOUR CLASS in the class documentation with a few sentences describing what your objective function does.
  4. Replace YOUR NAME HERE on the author line of the class documentation with your name.
  5. Replace all uses of ObjectiveTemplate with OBJECTIVE. 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 objective function that will be visible in the Comparator. The NAME_OBJECTIVE variable should be set to the display name of your objective function. Unlike the class name, the display name can contain spaces and should be formatted like a title. The contents of the DESCRIPTION_INPUT variable will be displayed when the user requests information about what your objective function expects for input. You can also use this space to describe what your objective function will do with that input. The description may use HTML 3.2 tags to format the text. Descriptions for the objective functions included with the Comparator are in the BASE/jigcell/compare/function/resource/help directory.
  7. Add the code to perform your objective function under /* CODE TO PERFORM COMPUTATION */. Two IDataElements called input1 and input2 provide input to the objective function.

If your objective function encounters an error, it is best to handle the error and recover from it. Although the Comparator attempts to clean up objective functions that fail, it is not always successful. Your objective function should trap exceptions during evaluation and return cleanly. If a fatal exception occurs in your objective function, you can report that to the Comparator using the fireEvaluationError(Exception) method. If you have detected a fatal condition in your objective function 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 objective function to the user.

Optional Tasks

The only code you must provide for an objective function is to perform the computation. The objective function template also provides a stub for creating an interface for your objective function.

There are two ways to add a graphical interface to your objective function. 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 Objective 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 objective function uses. If you do not provide an interface, an empty one will be created for you by default.

Adding an Objective Function to JigCell

  1. Save OBJECTIVE.java.
  2. Compile your objective function 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 objective function 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.function.WOSSDataGenerator,. Insert ,jigcell.compare.contrib.OBJECTIVE after the last objective function and before the </string>.
  5. Save compare.config.
  6. Run make distro in BASE to generate installers containing your objective function. The installers will be located in BASE/www. This installer is used the same way as the normal JigCell installer.