Creating Java Algorithms

Summary

This tutorial describes how to create a simple "Hello World" Java Algorithm using CIShell's Algorithm Development Wizard in Eclipse.

Pre-requisites

You will want to be familiar with the basics of Java CIShell Algorithms. Where applicable, each step will link to the relevant basics page for details.

You will need to have set up your development environment as described in "Setting Up the Development Environment", and will need to have installed a CIShell tool, as described in "Downloading a CIShell tool".

 It may be helpful to have the CIShell 1.0 specification available to you for reference purposes.

Section Table of Contents

1. Creating an Algorithm
2. Exporting an Algorithm for Use

Creating an Algorithm

Creating a CIShell Algorithm is a simple process with our CIShell Algorithm Development Wizards. To create a CIShell Java Algorithm Project, go to File->New->Project... and expand the CIShell group of wizards.

Figure 1: Available CIShell Algorithm Projects.

Select Java Algorithm Project and press Next >. On the next screen, fill in a project name and press Next >. (As a convention, we usually make the project name, package name, and symbolic name identical for CIShell plugins, as you will see in the following steps).

The next page requires input about your bundle. The Bundle Name (Bundle-Name) is a name for your algorithm bundle as a whole, which can just be the name of the algorithm. The Bundle Symbolic Name (Bundle-SymbolicName) is the name CIShell will use to refer to this plugin internally. The Bundle Version (Bundle-Version) should be the version number of your algorithm. See Bundle Properties and Java Interfaces for more details. Use the default values, an click Next > to go to the next page.

Figure 2: Bundle Properties.

The next page requires input about your algorithm. Algorithm Name (label) is the name of your algorithm as it will appear on a CIShell application's menu bar. Algorithm Description (description) will describe what your algorithm does in CIShell. Algorithm Class Name will be the name of the Java Algorithm class generated. It is conventional to have all algorithm classes end with "Algorithm" in CIShell.Algorithm Package will be the Java package of the Algorithm class that will be generated. This should be the same as the project name. Click Next > to go to the next page.

Figure 3: Algorithm Properties.

The next page requires input about how the algorithm will work. Data the algorithm will take in (in_data) says what data the algorithm will take in (if any) to process. Data the algorithm will produce (out_data) says what data the algorithm will return (if any). If your algorithm will not be creating its own GUI (i.e., visualizations) and meets the requirements for a remoteable algorithm, check Remoteable Algorithm (remoteable). If your algorithm should be visible on a CIShell applications's menu bar, check On the menu and fill in Menu path and Menu item placement (menu_path). This says where to place the algorithm on the menu. It is a '/' separated path, that also says where on the specific submenu to place the algorithm. See Service Properties for more details. Click Next > to go to the next page.

Figure 4: More Algorithm Properties.

The next page allows you to specify what additional input parameters are needed from the user. Use the Add button to add as many extra inputs as needed. There are many different types of inputs including strings, numbers, files, and directories. Please make sure the id's are unique. When the algorithm is ran, this information is used to create a GUI for the user to input responses. A Dictionary of the entered responses going from the id to the value entered is given to the createAlgorithm method. See Input Parameters for more details.

Figure 5: Algorithm Input Parameters.

Finally, press the Finish button to generate a new Java Algorithm project. This is what should appear in Eclipse:

Figure 6: Resulting Java Algorithm project.

Several files are generated for the project:

• Two Java classes are generated, an Algorithm class and its associated AlgorithmFactory class, see Java Interfaces.
• A MANIFEST.MF containing the Algorithm's bundle properties, see Bundle Properties.
• A bundle_en.properties file for internationalization, see Input Parameters.
• A METADATA.XML file holding the Algorithm's user-entered input parameters, see Input Parameters. The METADATA.XML file can also be used for User-Adjustable Preferences.
• An algorithm.properties file holding the algorithm's properties, see Service Properties.
• A component.xml file which registers the algorithm to OSGi's Service Registry, see DS Service Registration.
• A build.properties file which enumerates what files/directories are to be included when creating an OSGi bundle from the project.

Figure 7: Files in the Algorithm project.

Exporting an Algorithm for Use

To test the Algorithm, right click on the project name and click Export. In the new dialog expand the Plug-in Development category and select Deployable plug-ins and fragments, then click Next >.

On the next page, check the algorithm bundle to export as an OSGi Bundle and set the destination directory to be where a CIShell application is installed. Click Finish to export the algorithm bundle.

Figure 8: Algorithm Export.

You should now be able to run the CIShell application and test the Algorithm. If you export again and have changed any properties, please run the CIShell application with the "-clean" command-line switch. See the "Algorithm Development Tips And Tricks" section for other useful techniques for debugging algorithms.

Dev Guide Home