TODO: Replace all screenshots to more accurately reflect the tutorial content.
This guide describes how to create a simple "Hello World" Java Algorithm using CIShell's Algorithm Development wizard in Eclipse.
You will want to be familiar with the basics of Java CIShell Algorithms described in CIShell Basics. You will need to have set up your development environment as described in "Setting Up the Development Environment".
It may be helpful to have the CIShell Specification available to you for reference purposes.
Section Table of Contents
- Creating the Algorithm project
- Writing the Java code for the Algorithm
- Exporting an Algorithm for Use
- Debugging Tips
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, Bundle Properties, requires input about your algorithm 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. Use the default values, and click Next > to go to the Algorithm Properties page.
Figure 2: Bundle Properties.
The Algorithm Properties page requires input about your algorithm. Algorithm Name (label) is the name of your algorithm as it will appear in a CIShell application's menu. Algorithm Description (description) will be used as documentation to 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.
Change the Algorithm Name to "Hello World", the Algorithm Description to "Prints 'Hello World!' to the Console", and the Algorithm Class Name to "HelloWorldAlgorithm". The package can stay as 'org.my.algorithm'. Click Next > to go to the second Algorithm Properties page
Figure 3: Algorithm Properties. (TODO: Update this, and possibly all, screenshots to reflect desired field values).
The second Algorithm Properties 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 application'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 the OSGi specification for more details.
For this tutorial we should set both data taken in and data produced to "null". Check the "On the menu" checkbox, and set the Menu path to "AwesomeAlgorithms/". Set menu item placement to "Anywhere". When you are finished, click Next > to go to the Algorithm Parameters page.
Figure 4: More Algorithm Properties.
The next page allows you to specify what additional input parameters are needed from the user. You can 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. When the algorithm is run, this information is used to create a GUI for the user to input responses. The id field for each input parameter will be used as a key to obtaining the values provided by the user (please make sure the id's are unique). The name field will label each input parameter on the GUI. The description field will become the help text associated with each input parameter.
For this tutorial we do not need to create any algorithm parameters.
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.
- A MANIFEST.MF containing the Algorithm's bundle properties.
- A bundle_en.properties file for internationalization.
- A METADATA.XML file holding the Algorithm's user-entered input parameters (see OSGi Compendium 'Metatype Service Specification' Section 105
- An algorithm.properties file holding the algorithm's properties (see CIShell Specification 'Service Metadata' Section 2.3.3).
- A component.xml file which registers the algorithm to OSGi's Service Registry (see OSGi Compendium 'Declarative Services Specification' Section 112).
- 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.
Writing the Java code for the Algorithm
You should now see an open project with the name "org.my.algorithm" in your Eclipse workspace. If you open the "src" folder in this project, you should see the package "org.my.algorithm", which we created in the wizard. Expanding this package, you should see two classes: HelloWorldAlgorithm.java, and HelloWorldAlgorithmFactory.java. These two files are the basis of almost all Java algorithms in CIShell.
Algorithms in CIShell almost always have their own factory class, which helps to create the algorithm. Opening HelloWorldAlgorithmFactory, you can see that the algorithm factory has a "createAlgorithm" method, which creates and returns the "HelloWorldAlgorithm" object. Sometimes you will need to modify the AlgorithmFactory, but for this simple tutorial it does not need modification, so we can go straight to modifying the HelloWorldAlgorithm file itself.
The contents of HelloWorldAlgorithm should look like this:
In its current state this algorithm will run perfectly well in a CIShell tool, but we need to add a few lines to make it do something.
In order to print our "Hello World!" message to the console, we must get the LogService from the CIShellContext.
The full code for our simple HelloWorld algorithm is as follows:
In the constructor we obtain the LogService by passing its class name to the getService method of the CIShellContext. CIShell guarantees that the LogService and several other services will always be available using this technique. For more information see the CIShell Specification.
Once we have obtained the LogService in the constructor, we are able to print our "Hello World!" message in the execute() method.(Incidentally, the constructor should not be used to perform the main work of the algorithm, as only the execute method is guaranteed to be called at the appropriate time. An algorithm may theoretically be constructed and held for a long period of time, but only executed much later).
The first argument, LogService.LOG_INFO, ensures that the message is only meant to be informative, in contrast with LogService.WARNING, which is used for non-fatal errors. Fatal errors (errors which cannot be recovered from) should be thrown as AlgorithmExecutionExceptions.
(It is also possible to simply use ' System.out.println("Hello World!") ' to print a message from a CIShell algorithm, but this message will be routed to the OSGi console instead of the standard user-visible CIShell console. To see the OSGi console, which can be useful for debugging purposes, start your CIShell tool as described in Accessing the OSGi Console in CIShell tools.)
Our "Hello World!" CIShell Algorithm is now complete.
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. Do not export to the 'plugins' directory of a CIShell tool directly, even though this is the final destination of the plugin, as this will cause your plugin to be exporting to a plugins directory within the real plugins directory (Eclipse append "/plugins" to the path of whichever directory you choose). Click Finish to export the algorithm bundle.
Figure 8: Algorithm Export.
We should now be able to run the CIShell application and test the Algorithm. To see your algorithm in action, start your CIShell tool, and choose the algorithm from the menu "AwesomeAlgorithm" which should appear along the top menu bar. The message "Hello World!" should print in the Console.
If something goes wrong, and there is no obvious error message, first make sure that your plugin can be found in the CIShell tool's /plugins directory. If the plugin is present, try starting CIShell with the OSGi console, as described in Accessing the OSGi console in CIShell tools, and type 'ss'. This will list all the algorithms installed in your CIShell tool. Find the id associated with that plugin, and try typing "start ID" where ID is the number (say, 129). If OSGi had some error while trying to start your plugin, attempting to restart it in this way should cause the error to be printed to the OSGi console.
If you need to export your plugin again, and have changed any properties, please run the CIShell application with the "-clean" command-line switch (See Accessing the OSGi console in CIShell tools.Tutorial 2: Practical Java Algorithm Development
If you need to run a real debugger, with breakpoints and so on, this is possible. See How to Debug Sci2 with Eclipse.