Skip to content

Tool specifications

Jump to bottom
cneud edited this page Nov 1, 2012 · 5 revisions

Introduction

This page provides a walkthrough of an example tool specification, an XML description file for any given command line tool used for integrating command line tools with the tool wrapper. The schema for the tool specifications can be found here.

The toolspec.xml contains three main sections:

  1. id/installation: background information on the command line tool

  2. services: detailed description of the web service(s) and related operations

  3. deployments: configuration of local/remote deployment parameters

The use of the toolspec.xml is hereafter demonstrated by example of the copy command.

id/installation

In this section, background information on the given command line tool is provided. The following elements are available:

  • <id>
    Concise identifier for the command line tool.
  • <name>
    Name of the command line tool.
  • <homepage>
    URL of the tool/project homepage.
  • <version>
    Version number of the tool/project
    Note that '.' dots are not supported and will be converted to '-' dashes instead.
  • <installation>
    Additional information on the tool such as system requirements, download location and installation procedure.
    • <os>
      Operating system specific details can be listed here specified by an attribute @type.

Example

    <id>cp</id>
    <name>Copy</name>
    <homepage>http://en.wikipedia.org/wiki/Cp_%28Unix%29</homepage>
    <version></version>
    <installation>
        <os type="linux">
            Available by default.
        </os>
        <os type="windows">
            Use "CMD.exe /C COPY" instead of "/bin/cp" in the command defined below.
        </os>
    </installation>

services

In this section, a detailed description of the web service(s) and according operations is given. The following elements are available:

  • <service>
    A tool can have multiple service descriptions, each of which can in turn have the following attributes:
    @sid = service ID
    @name = service name
    @type = migrate
    @servicepackage = web service package
    @contextpathprefix = prefix for deployment context
  • <operation>
    A service can have multiple operations, identified by their attributes @oid and @name.
  • <description>
    Human readable description of the operation
  • <command>
    Command line skeleton with replacement variables encoded by '${value}'
  • <inputs>
    An operation can have multiple inputs, identified by the attribute @name. For every input, the following child elements need to be provided:
    • <Datatype>
      Input datatype - currently supported are 'xsd:anyURI', 'xsd:int', 'xsd:boolean' and 'xsd:string', 'xsd:string_restricted', 'xsd:string_restricted_list'
    • <Required>
      Indicate whether input is required 'true' or only optional 'false'
    • <CliMapping>
      Name of corresponding replacement variable from the <command> element above
    • <Documentation>
      Documentation of the input (will be exposed as WSDL annotation)
    • <Default>
      A default value for the input
  • <outputs>
    An operation can have multiple outputs, identified by the attribute @name. The following child elements need to be provided:
    • <Datatype>
      Output datatype - currently supported are 'xsd:anyURI', 'xsd:int', 'xsd:boolean' and 'xsd:string', 'xsd:string_restricted', 'xsd:string_restricted_list'
    • <Required>
      Indicate whether output is required 'true' or only optional 'false'
    • <CliMapping>
      Name of corresponding replacement variable from the <command> element above
    • <Documentation>
      Documentation of the output (will be exposed as WSDL annotation)
    • <PrefixFromInput>
      Indicate whether the input file name should be added as a prefix to the output file name
    • <Extension>
      Indicate a suffix to be added to the output file name
  • <deployTo>
    Specify which of the available deployments (configured below) shall be used by the service

Example

    <services>
        <service sid="1" name="Simple Copy" type="migrate" servicepackage="eu.impact_project.iif.services" contextpathprefix="/impactservices">
            <description>Service for copying files</description>
            <operations>
                <operation oid="1" name="simpleCopy">
                    <description>Copies a file</description>
                    <command>/bin/cp ${input} ${output}</command>
                    <inputs>
                        <input name="inputUrl">
                            <Datatype>xsd:anyURI</Datatype>
                            <Required>true</Required>
                            <CliMapping>input</CliMapping>
                            <Documentation>URL reference to input file</Documentation>
                            <Default>http://localhost:8080/test.txt</Default>
                        </input>
                    </inputs>
                    <outputs>
                        <output name="output">
                            <Datatype>xsd:anyURI</Datatype>
                            <Required>false</Required>
                            <CliMapping>output</CliMapping>
                            <Documentation>URL reference to output file</Documentation>
                            <PrefixFromInput>input</PrefixFromInput>
                            <Extension>txt</Extension>
                        </output>
                    </outputs>
                </operation>
            </operations>
            <deployto>
                <deployref default="true" ref="local"/>
            </deployto>
        </service>
    </services>

deployments

In this section, the local/remote deployments can be configured.

This requires that Tomcat is used as the servlet container since the automatic deployment via Maven method requires Tomcat's manager application. If you are not using Tomcat as your servlet container, you need to deploy the WAR manually.

The following elements are available:

  • <deployment>
    A tool can have multiple deployment descriptors, each of which are referenced by an attribute @id.
  • <identifier>
    Reference to a human-readable description of the deployment environment (system specs, admin contact).
  • <host>
    Domain name of the server that the web service shall be deployed to.
  • <ports>
    Port numbers for HTTP/HTTPS transport to the server. Protocol is determined by attribute @type.
  • <manager>
    In this section, the configuration for the Tomcat manager application can be specified.
    Note that in Tomcat version 7.0 or later the role name for the manager application has been altered to 'manager-script'
    • <user>
      User name of the user with the role 'manager' - can be configured in Tomcat's tomcat-users.xml.
    • <password>
      Password for the user with the role 'manager' - can be configured in Tomcat's tomcat-users.xml.
    • <path>
      URL pattern for the relative path to Tomcat's manager application.
      Note that in Tomcat version 7.0 or later the default path to the manager application has been altered to 'manager/text'
  • <toolsbasedir>
    Here the working directory for the tool can be defined (by default, the CWD is used).
  • <dataexchange>
    This section holds the mapping of local output files to URLs.
    • <accessdir>
      Absolute path to the local directory which is used to hold output files from web service operations.
      Note that the user which is running Tomcat needs to have write permission for this directory
    • <accessurl>
      Absolute URL under which the contents of the accessdir are mapped for remote access.
      Note that this URL should be accessible from the web in order to enable processing with other services

Example

    <deployments>
        <deployment id="local">
            <identifier>http://localhost:8080/impact/instances/tomcat1</identifier>
            <host>localhost</host>
            <ports>
                <port type="http">8080</port>
                <port type="https">8043</port>
            </ports>
            <manager>
                <user>tomcat</user>
                <password>tomcat</password>
                <path>manager</path>
            </manager>
            <toolsbasedir></toolsbasedir>
            <dataexchange>
                <accessdir>src/main/webapp/</accessdir>
                <accessurl>http://localhost:8080/impactservices/impact-simplecopy10-service/</accessurl>
            </dataexchange>
        </deployment>
        <deployment id="public">
            <identifier>http://myhost.com/impact/instances/tomcat2</identifier>
            <host>myhost.com</host>
            <ports>
                <port type="https">443</port>
            </ports>
            <manager>
                <user>tomcat</user>
                <password>tomcat</password>
                <path>manager</path>
            </manager>
            <toolsbasedir>local/impactservices/</toolsbasedir>
            <dataexchange>
                <accessdir>local/impactservices/out/</accessdir>
                <accessurl>http://myhost.com/impactservices/out/</accessurl>
            </dataexchange>
        </deployment>
    </deployments>

Have a look at the examples for more tools!

Clone this wiki locally