Service Integration Framework
 
Section 8.6: Service Integration Framework
The Service Integration Framework makes it easy to integrate command line tools that are installed on the server as services that operate on data and content within RAMADDA. There are a number of examples at ramadda.org. All RAMADDA repositories (running the latest release) have their list of enabled services at http://ramadda.org/repository/services/list.

To enable an installed service you need to specify one or more properties in a .properties file in your RAMADDA home directory that specify the location of the installed software. Below is the full set of properties that ramadda.org is using for the various plugins that are available. The /usr/local/bin and /opt/local/bin are just where different packages happened to be installed.
#################################
#General media
#################################

#ImageMagick
#Where convert, etc., are installed
service.imagemagick=/opt/local/bin

#PDFBox
#See pdfbox.sh
service.pdfbox=<path>/pdfbox/pdfbox.sh


#Quicktime tools  
#Where qt_info, qt_export, etc. are 
service.qttools=/usr/local/bin


#################################
# Geo data
#################################

#NetCDF Operators - NCO 
service.nco.ncwa=/opt/local/bin/ncwa

#Climate data operators - CDO 
service.cdo=/opt/local/bin/cdo

#GDAL
service.gdal.gdal_translate=/usr/local/bin/gdal_translate
service.gdal.gdalinfo=/usr/local/bin/gdalinfo

#HDF5 tools 
service.hdf5.h5ls=/opt/local/bin/h5ls


#MB System Bathymetry  data 
service.mb.mbinfo=/usr/local/bin/mbinfo
service.mb.mblist=/usr/local/bin/mblist


#################################
#Bioinformatics
#################################

#Dicom image tools dcm4che
service.dicom.dcm4che=<path>/dcm4che-2.0.28/bin

#OME Bio-Formats                                                                
#http://www.openmicroscopy.org/site/support/bio-formats5/users/comlinetools/    
service.bfconvert = <path>/bftools/bfconvert

#SRATools - 
service.sratools=<path>/sratoolkit.2.3.5-2/bin

#HMMER Tools - 
service.hmmertools=<path>/hmmer-3.1b1-macosx-intel/binaries

#Picard - 
service.picard=<path>/picard-tools-1.119/picard.sh

A service is specified as either an outputhandler XML file or a services XML plugin. There are numerous examples under the SVN source tree at http://sourceforge.net/p/ramadda/code/HEAD/tree/src/org/ramadda/ Below is an example of two output services, one defined inline and the other referencing a service defined in the below services.xml file. There are enabled by setting the properties in a .properties file:
service.test1=/path/to/program
service.test2=/path/to/program
Note: To install as a plugin remove the "_ex1" so you have an outputhandlers.xml plugin file.
<outputhandlers class="org.ramadda.repository.output.ServiceOutputHandler">
<!-- You can specify attributes that are inherited by all services, e.g., class="ServiceOutputHandler" 
This xml can either contain the service xml directly
or it can refer to a service that was defined in a separate services.xml file -->

  <outputhandler  category="Test Output">
<!-- Set a property service.test1=/path/to/executable.sh in a .properties file in your RAMADDA home dir -->
    <service id="test_service1"  command="${service.test1}" label="Run example service 1" icon="/icons/pdf.png" >

<!-- Specify an entry of a particular type (type_document_pdf) -->
       <arg value="${entry.file}" type="entry" entryType="type_document_pdf" primary="true" label="Input PDF File" ></arg>

<!-- ... There would be other service attributes here. See services.xml ... -->

    </service>
  </outputhandler>

<!-- Or you can have the output handler reference the service id from a services.xml file -->
  <outputhandler  category="Test Output" serviceId="test_service2"/>


</outputhandlers>
examples/outputhandlers_ex1.xml
Services can be defined in a separate services.xml file.
<services>
<!-- Set a property service.test2=/path/to/executable.sh in a .properties file in your RAMADDA home dir -->
    <service 
       id="test_service1"  
       command="${service.test2}" 
       label="Run example service 1" 
       icon="/icons/pdf.png" >
    <description><![CDATA[Runs an example service]]></description>
<!-- Define the command line arguments -->

<!--
Each arg tag has the following attributes:
type (string, flag, enumeration, value,int, entry, etc)
name - the url argument id 
value - a value to use - may contain ${...} macros
label
help - shown in the form
values - list of comma separated enum values
prefix - added to the arg list if the value is defined
-->


<!-- Always have 'any value' as an arg -->
       <arg value="any value"/>

<!-- specify type='enumeration' for a pull down list. Add the "none" item -->
       <arg name="fruit1" type="enumeration" values="apple,banana,orange" addNone="true"/>

<!-- specify value:label pairs -->
       <arg name="fruit2" type="enumeration" values="apple:Apple label,banana:Banana label,orange:Orange label"/>

<!-- Specify a value attribute where the macro '${value}' is replaced with the selected value -->
       <arg name="fruit3" type="enumeration" values="apple,banana,orange" value="fruit=${value}"/>

<!-- Input field -->
       <arg name="string1" type="string" size="50"  label="Some string" help="Help text goes after the field"/>

<!-- If the string is defined then also add the prefix as an argument -->
       <arg name="string2" type="string" size="50"  label="Some string" prefix="-string"/>

<!-- use an int type-->
       <arg name="length" type="int" default="5"  label="Length"/>


<!-- If checkbox is selected then add the value as an arg-->
       <arg name="flag1" type="flag"   label="Some flag" value="flag1 selected"/>

<!-- If checkbox is selected then add the "-someflag" "flag1" -->
       <arg name="flag2" type="flag"   label="Some flag" prefix="-someflag" value="flag1"/>

<!-- Args of type entry match up with specific entry types in ramadda -->
       <arg value="${entry.file}" type="entry" entryType="type_document_pdf" primary="true" label="Input PDF File" ></arg>

<!-- This uses the macro ${entry.file.base} to get the base name (minus the suffix) of the selected entry's file
So, if we having incoming.pdf the output file is incoming.txt -->
       <arg value="${file}" file="${entry.file.base}.txt"></arg>

<!--
Now define the outputs. Each output has a regexp pattern that matches on any generated file
You can specify an entry type for the entries that get created for each file
-->
       <output type="file" pattern=".*\.txt"/>
       <output type="type_image" pattern=".*\.png"/>

<!-- If the service produces text to the stdout then this specifies to write to a file -->
      <output showResults="true" stdout="true" filename="test.txt"/>
   
 </service>
</services>
examples/services_ex1.xml

One command line argument made up of multiple user choices.

Use the include attribute to provide a user interface element (e.g., date select) but not directly add the value to the command line arguments. Rather you can embed the value in a later argument with the "${name}" macro syntax. e.g. org/ramadda/geodata/cdmdata/resources/cdoservices.xml
//specify 2 date arguments
   <arg type="date" name="cdo.fromdate" label="Start Date" include="false" valuesProperty="dateList"/>
   <arg type="date" name="cdo.todate" label="End Date" include="false" valuesProperty="dateList"/>
//specify a simple value argument that includes the values of the two date args
   <arg value="-seldate,${cdo.fromdate},${cdo.todate}"/>
Here we have an image format enumeration value with include=false. It is used From org/ramadda/bio/image/services.xml
<arg type="enumeration" name="imageformat" label="Image type" values="png,gif,jpg,tiff" include="false" default="png"/>

//Specify an entry
<arg value="${entry.file}" type="entry"  label="Input image file" primary="true" entryType="bio_dicom,bio_ome_tiff"></arg>

//Provide the output image
<arg value="${file}" file="${entry.file.base}${suffix}.${imageformat}"/>