From Informatics

If you want new services to be recognized by the Dispatcher on production, you'll need to follow these production steps.

Creating a geWorkbench Grid Analysis Component

Client Side

This discusses how to take an existing geworkbench component make it a usable grid client for a grid service.

Take your existing analysis that extends AbstractAnalysis and make it extend AbstractGridAnalysis. Your IDE should tell you that you need to implement some methods. Implement these. See FastHierClustAnalysis as an example.

Server Side

This discusses how to create the actual grid service.

Before creating this service, you must configure your local machine to use the caGrid infrastructure as described in CaGrid 1.1-final.

Set up

Before starting, make sure you have checked out the following projects in your eclipse_cagrid_workspace:

dispatcher - open this with Introduce and click save.
ginkgo - this is not a grid service.
checkout geworkbench into your workspace from the command line and don't import it into eclipse.

Open another eclipse workspace specific to geworkbench. See Geworkbench Eclipse Setup - be aware that this is not the latest setup after migration to github. This should have:

geworkbench-core
<your component>

Then, make sure you have configured your local instance of tomcat correctly. This is discussed here.

User account

copy userInfo.txt from under Dispatcher\metadata\ in workspace to %CATALINA_HOME%\temp\Dispatcher\

Create the service using introduce

Use Introduce to create a new grid analysis component
- under the directory you installed caGrid, use command "ant introduce" to launch Introduce.
- click on "Create caGrid Service"
- In the wizard:
  - choose the directory where you want to create your service source code.
  - Enter name of the service
  - Enter the package name (for example: edu.columbia.geworkbench.cagrid.som )
  - change the namespace for the generated WSDL if you want (introduce will guess one for you)
  - select "Analytical Service"
  - click on create
- Once introduce has finished creating the service, you will be able to modify the service interface. (Look at one of the already implemented services like SomClusteringService as an example)
  - In the "Import Data Types", click on "File System" and browse & select the .xsd files which you may have created (for each class which goes as a parameter into the service's execute method). Add the xds files.
  - Click on "Operations" tab and add a new method - execute with two input parameters and a return type: (these types must have been imported in the last step)
    - first parameter: Input object which goes into the service as input.
    - second parameter: ClusteringParameter object, which will contain all the input parameters for the service.
    - return type: result object of the service.
- once you have done this, you can save the service and the basic service implementation by introduce is done .

Modify the service created by introduce

Now you can open the code in eclipse and modify it to make it accessible and invokable by dispatcher service.

Now modify the service as follows:

add any other third party jars (to the lib dir of your service) you may need while implementing the actual business-logic of the service.
cd to ginkgo and type:

ant -f build-server.xml updateGinkgoJars
ant -f build-server.xml compileGeworkbench
ant -f build-server.xml  updateBisonJars

This copies the following jars to your service:
- ginkgo-0.1-SNAPSHOT.jar
- bison-0.1-SNAPSHOT.jar
Implement GridServiceClient (in addition to the exiting XXXI class) in the xxxClient class, in edu.columbia.geworkbench.cagrid.xxx.client package (where xxx is your service name).
Eclipse will then ask you to write your own code for the following methods:
- public String execute(String encodedInput) : this method will be called by dispatcher service. The input string is the encodedInput which will contain the input parameters for the service. You will need to decode this string to get GridInput object and extract service inputs from that. This method should return the output of the service as an encoded string. ( Look at SomClusteringClient for reference).
- public Serializable convertResultToBison(Serializable arg0, Class arg1): This method should contain the logic to convert the service result object to a grid object. This method should be called from execute logic above before encoding the service output.

Implement the service

Extract the input parameters from the encoded string in this execute method and call the original execute method (created by introduce) with these input parameters.
Implement your service fully now. You can make use of helper classes and call the appropriate methods from the execute method.
You should implement the algorithm of the service only in one place and use it in both local and grid version. ex: Write a class to do the main calculation, jar it and call it in both local and grid version. In grid version, you probably need to convert the data from grid data structure to bison data structure before calling the JARed version.

Providing dispatcher with the client, common and stubs jars

Once you are done implementing the service, the next step is to put following three jars in the dispatcher/lib directory inside the dispatcher project. This can be done using ant or manually.

Using ant:

cd to ginkgo and type ant -f build-server.xml copyClientsToDispatcher

Manually:

refresh eclipse project and it will build the project.
go to xxx/build/lib directory, copy xxx-common.jar & xxx-stubs.jar and paste them into dispatcher/lib directory.
Create client jar for the service:
- right click on the project node in the eclipse for this service.
- click on export.
- select "jar" option inside "java" option and click on next.
- expand the project node in the next window, unselect everything and just select "edu.columbia.geworkbench.cagrid.xxx.client" node.
- browse and select the jar location as "dispatcher/lib" directory.
- click on finish.

Telling dispatcher about the new service

Open dispatcher.properties under ginkgo/metadata inside ginkgo project.
Add your service name at the end of the "service.name" key (comma separated).
Add the fully qualified class name of the client of your service add the end of the "service.client" key (comma separated).

Telling your service about the index service

Open deploy.properties present in your service. (Deploying your service would make this entry available.)
Give appropriate url of the index service in the "index.service.url" key.

Deploying the Service(s) and Dispatcher

First, see pre-deployment.

This can be done via ant or manually.

Using ant:

cd to ginkgo and type:

ant -f build-server.xml deployComponents
ant -f build-server.xml deployDispatcher

Manually: Please see Deploy caGrid Service using introduce

CVS Check list

Once you have tested your changes and are sure they work, make sure you check the following into cvs:

XXX-client.jar, xxx-common.jar & xxx-stubs.jar in dispatcher/lib of the dispatcher project.
dispatcher.properties under ginkgo/metadata of the ginkgo project.
any changes in your own project.

Debug

See Axis and CaGrid_Debugging for information on how to configure logging (for axis and grid services), run web-services in debug mode, etc.

Dispatcher Aware