Introduction
A general reference which describes the function of each file in an algorithm plugin, and describes the details of how algorithms are registered, added to the menu, and executed.
Prerequisites
Readers should understand the basics of CIShell Algorithms, and may also find this information more relevant after having explored the tutorials which are part of this development guide.
Section Table of Contents
Introduction
In OSGi, the main functional units are called "Services". Services are exposed through the OSGi Registry Service, which other services can search through to find services they would like to interact with. CIShell AlgorithmFactories are registered as services using the "Declarative Services" method of service registration. Declarative Services inspects every plugin in CIShell, looking for special Service-Component xml files, which contain all the information OSGi needs to register the services in these plugins. Full details on Declarative Services can be found in the OSGi Compendium Specification. The remainder of this document attempts to describe the most important details of relevant to CIShell algorithms.
How Algorithms are Registered
Declarative Services examines the manifest of each plugin, looking for the 'Service-Component' property. This property points to zero or more service component xml files (plugins built with the Java algorithm wizard in CISHELL have one service component file by default, component.xml). The Service component file has three important aspects relevant to CISHELL: the <implementation> tag references the Java AlgorithmFactory which will be instantiated when this service is requested. The <properties> tag links this service to the properties which describe it, which can be found in the algorithm.properties file. The <service> tag describes which interface the class reference in the <implementation> tag will be registered under. In CIShell, we only register classes using the 'AlgorithmFactory' interface, relying on the service.pid property to uniquely identify the service. Declarative Service wil register the service using the information referenced in this component.xml file.
How Algorithms are Added to the Menu
There are two ways algorithms are added to the menu. First, if an algorithm is listed in the default_menu.xml file, which is found in the configuration/ directory of a CIShell tool, it is added in the place specified by the default_menu.xml file. Secondly, if an algorithm is not listed in this file, but has specified a menu_path property in the algorithm.properties file, the menu manager CIShell service will add it to the appropriate menu, as described in the by the menu_path property's value (for example, Analysis/additions will place an algorithm on the bottom of the Analysis menu).
How Algorithms are Executed
When a user selects an algorithm from the CIShell menu, a sequence of steps occurs. First, the METADATA.XML in the plugin of the selected algorithm is inspected. The <Designate> element whose pid (persistent ID) matches the service.pid of the algorithm is used to point to the appropriate <OCD> (ObjectClassDefinition) element. The OCD element describes the user-parameters the algorithm requires.
Next, if the AlgorithmFactory of the selected algorithm implements MutateParameters, the OCD object resulting from the METADATA.XML file is passed into the mutateParameters method of the AlgorithmFactory, to allow the AlgorithmFactory to mutate the OCD before it is presented in GUI form the user.
The OCD is then rendered as a GUI by the GUIBuilder service, and the user selects values for each of the displayed fields in the GUI.
The association between fields and values is then used the create the parameters Dictionary object.
The Data selected from the Data Manager is also obtained, as is the CIShellContext.
Now that we have all the required parameters for the Algorithm, the AlgorithmFactory of the algorithm is obtain, and its createAlgorithm method is called using the data, parameters, and CIShellContext we obtained.
After the algorithm runs, the resulting data is collected, and given to the Data Manager.