# Brutex XServices Documentation

February, 16th 2010
Brian
Rosenberger
bru@brutex.de
Brutex Network
2011

The copyright holders make no representation about the suitability of this document for any purpose. It is provided as is without expressed or implied warranty.

Apache Tomcat and Apache Ant are trademarks of the Apache Software Foundation.

## Abstract

In complex IT environments it is necessary to integrate different information systems with each other, exchange data between tools and automate actions and function calls depending on events arising from user interaction. To meet the requirements of integration building usually means to implement APIs and to create tool-to-tool bridges. Web Services can help to clean up bridges into interfaces as well as to abstract functions from their underlying platform and implementation.

These are the major goals of the loosely coupled integration strategy which is in turn one essential idea of a service-oriented architecture (SOA).

provide a low level set of functions and web services. These can be orchestrated into services and used in business processes which make up the execution part of a SOA environment.

is an add-on to XBridgeNG 2.0. It runs standalone or in combination with XBridgeNG. Pure XBridgeNG has two components:

- XML Schema for item based data types (e.g. tickets from a bug tracker system or a database record)

- Set of Apache Ant tasks to function as a bridge between the XBridgeNG XML format at legacy 3rd party software (e.g. HP Quality Center, Serena TeamTrack, ...)

- The add Web Services (SOAP) wrapper around Apache Ant tasks (since XBridgeNG 2.0)

The current focus is on file-based operations. do not contain an integration server or a process execution engine.

## Getting started

This chapter describes the installation.

#### Installation

tbd.

Sun Java SE 1.6.0

Apache Tomcat 7

tbd.

In short: Deploy .WAR file to Apache Tomcat

##### Securing with Basic Authentication

There is a quick guide explaining Basic Authentication for Tomcat here: http://oreilly.com/pub/a/java/archive/tomcat-tips.html?page=1

##### Limit access to

Sometimes you'll only want to restrict access to to only specified host names or IP addresses. This way, only clients at those specified addresses can use the web services. Tomcat provides two configuration values for that: RemoteHostValve and RemoteAddrValve.

These Valves allow you to filter requests by host name or by IP address, and to allow or deny hosts that match. The example below restricts access to the ArchiveService from any machine that is not the local host.

    <Context
    				path="/XService/ArchiveService"
    				...> <Valve
    				className="org.apache.catalina.valves.RemoteAddrValve"
    				allow="127.0.0.1" deny=""/> </Context>

If no allow pattern is given, then patterns that match the deny attribute patterns will be rejected, and all others will be allowed. Similarly, if no deny pattern is given, patterns that match the allow attribute will be allowed, and all others will be denied.

The <context> element must be placed into the server.xml file (into <engine><host>).

## Available Services

List of available web services and their operations.

### ArchiveServices

The ArchiveService bundles file packing operations. Its WSDL is located at http://server:port/XServices/ArchiveService?wsdl

### DateServices

The DateService bundles various date and time related operations. Its WSDL is located at http://server:port/XServices/DateService?wsdl

### ExecuteServices

The ExecuteService bundles local and remote command execution operations. Its WSDL is located at http://server:port/XServices/ExecuteService?wsdl

#### rExec

provides remote execution facilities with authentication based on user names and passwords.

##### Input parameters

###### rExec input parameters

parameter | type | required | description
--- | --- | --- | ---
host | HostConnection | Yes | Host where to execute the command. See HostConnection .
command | String | No | Any command including arguments
timeout | Long | Yes | Timeout in milliseconds. The command is forcefully terminated when timeout is reached.

##### Output parameters

###### ReturnCode type

The ReturnCode type is used as the generic answer type for most of the BruteXservices operations.

The defining Java class is `net.brutex.xservices.types.ReturnCode` .

Schema definition

    <xs:complexType name="ReturnCodeType">
        <xs:sequence>
            <xs:element name="returnCode" type="xs:int"/>
            <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
            <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="tns:antProperty"/>
        </xs:sequence>
    </xs:complexType>

Example XML

    		<ReturnCode
    		xmlns:ns2="http://ws.xservices.brutex.net">
    		<returnCode>0</returnCode>
    		<stdOut/>
    		<stdErr/>
    		<propertyList>

    			See
    			tns:antProperty
    			for details about the <propertyList> elements.

    		<name>key1</name>
    		<value>value1</value>
    		</propertyList>
    		<propertyList>
    		<name>key2</name>
    		<value>value2</value>
    		</propertyList>
    		</ReturnCode>

#### runCommand

Run an executable with arguments on the server providing the web service. The command is run within the environment and under the user privileges of the user who is running the Tomcat Server.

##### Input parameters

###### runCommand input parameters

parameter | type | required | description
--- | --- | --- | ---
executable | String | Yes | Command to be run. The command may be specified with full path using forward slash "/" as path separator.
argline | String | No | Any command line arguments
timeout | Long | Yes | Timeout in milliseconds. The command is forcefully terminated when timeout is reached.

##### Output parameters

###### ReturnCode type

The ReturnCode type is used as the generic answer type for most of the BruteXservices operations.

The defining Java class is `net.brutex.xservices.types.ReturnCode` .

Schema definition

    <xs:complexType name="ReturnCodeType">
        <xs:sequence>
            <xs:element name="returnCode" type="xs:int"/>
            <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
            <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="tns:antProperty"/>
        </xs:sequence>
    </xs:complexType>

Example XML

    		<ReturnCode
    		xmlns:ns2="http://ws.xservices.brutex.net">
    		<returnCode>0</returnCode>
    		<stdOut/>
    		<stdErr/>
    		<propertyList>

    			See
    			tns:antProperty
    			for details about the <propertyList> elements.

    		<name>key1</name>
    		<value>value1</value>
    		</propertyList>
    		<propertyList>
    		<name>key2</name>
    		<value>value2</value>
    		</propertyList>
    		</ReturnCode>

#### runCommandWithSSH

Executes a command through a SSH session.

##### Input parameters

###### runCommandWithSSH input parameters

parameter | type | required | description
--- | --- | --- | ---
host | HostConnection | Yes | Host to connect to (see: tns:HostConnection )
command | String | No | The command to execute.
timeout | Long | Yes | Timeout in milliseconds. The command is forcefully terminated when timeout is reached.

##### Output parameters

###### ReturnCode type

The ReturnCode type is used as the generic answer type for most of the BruteXservices operations.

The defining Java class is `net.brutex.xservices.types.ReturnCode` .

Schema definition

    <xs:complexType name="ReturnCodeType">
        <xs:sequence>
            <xs:element name="returnCode" type="xs:int"/>
            <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
            <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="tns:antProperty"/>
        </xs:sequence>
    </xs:complexType>

Example XML

    		<ReturnCode
    		xmlns:ns2="http://ws.xservices.brutex.net">
    		<returnCode>0</returnCode>
    		<stdOut/>
    		<stdErr/>
    		<propertyList>

    			See
    			tns:antProperty
    			for details about the <propertyList> elements.

    		<name>key1</name>
    		<value>value1</value>
    		</propertyList>
    		<propertyList>
    		<name>key2</name>
    		<value>value2</value>
    		</propertyList>
    		</ReturnCode>

##### Sample Request:

          <ws:runCommandWithSSH>
             <host>
                <hostname>ssh.brutex.net</hostname>
                <port>22</port>
                <user>roger</user>
                <password>xxx</password>
             </host>
             <command>ls /etc/</command>
             <timeout>30000</timeout>
          </ws:runCommandWithSSH>

#### telnet

Runs a telnet session with an "expect shell" like behaviour.

##### Input parameters

###### telnet input parameters

parameter | type | required | description
--- | --- | --- | ---
host | HostConnection | Yes | Host to connect to (see: tns:HostConnection)
prompt | String | No | The prompt string to expect after login. This is used to recognize when the session is open.
command | String | No | The command to execute.
expect | String | No | The prompt to expect after the command has been executed successfully.
timeout | Long | Yes | Timeout in milliseconds. The command is forcefully terminated when timeout is reached.

##### Output parameters

###### ReturnCode type

The ReturnCode type is used as the generic answer type for most of the BruteXservices operations.

The defining Java class is `net.brutex.xservices.types.ReturnCode` .

Schema definition

    <xs:complexType name="ReturnCodeType">
        <xs:sequence>
            <xs:element name="returnCode" type="xs:int"/>
            <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
            <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="tns:antProperty"/>
        </xs:sequence>
    </xs:complexType>

Example XML

    		<ReturnCode
    		xmlns:ns2="http://ws.xservices.brutex.net">
    		<returnCode>0</returnCode>
    		<stdOut/>
    		<stdErr/>
    		<propertyList>

    			See
    			tns:antProperty
    			for details about the <propertyList> elements.

    		<name>key1</name>
    		<value>value1</value>
    		</propertyList>
    		<propertyList>
    		<name>key2</name>
    		<value>value2</value>
    		</propertyList>
    		</ReturnCode>

##### Sample Request:

    	 <ws:telnet>
             <host>
                <hostname>localhost</hostname>
                <port>23</port>
                <user>brosenberger</user>
                <password></password>
             </host>
             <prompt>C:\Users\brosenberger&gt;</prompt>
             <command>dir c:\temp</command>
             <expect>enberger&gt;</expect>
             <timeout>60000</timeout>
          </ws:telnet>

### FileServices

The FileServces bundles various file operations. Its WSDL is located at http://server:port/XServices/FileService?wsdl

### MiscServices

The MiscService bundles various operations. Its WSDL is located at http://server:port/XServices/MiscService?wsdl

#### generateUUID

Generates a UUID that represents a 128-bit value. This operation does not require any input parameters. The output has the format:

    		0xFFFFFFFF00000000 time_low
    		0x00000000FFFF0000 time_mid
    		0x000000000000F000 version
    		0x0000000000000FFF time_hi

The least significant long consists of the following unsigned fields:

    		0xC000000000000000 variant
    		0x3FFF000000000000 clock_seq
    		0x0000FFFFFFFFFFFF node

Sample response:

    <soap:Envelope
    	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Body>
          <ns1:generateUUIDResponse
          	xmlns:ns1="http://ws.xservices.brutex.net">
             <ns1:return>33b9e5c8-9102-423b-88af-bbee479ebea8</ns1:return>
          </ns1:generateUUIDResponse>
       </soap:Body>
    </soap:Envelope>

#### getHostinfo

Collect information about a host address. Sample request:

    <soapenv:Envelope
    	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    	xmlns:ws="http://ws.xservices.brutex.net">
      		<soapenv:Header/>
      		<soapenv:Body>
    		<ws:getHostinfo>
            		<ws:hostname>google.com</ws:hostname>
         		</ws:getHostinfo>
      		</soapenv:Body>
    </soapenv:Envelope>

Sample response:

    <soap:Envelope
    	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      	<soap:Body>
          <ns1:getHostinfoResponse
          	xmlns:ns1="http://ws.xservices.brutex.net">
             <ns1:return>
                <ns1:domain>1e100.net</ns1:domain>
                <ns1:ip4>173.194.66.105</ns1:ip4>
                <ns1:ip6>::</ns1:ip6>
                <ns1:name>we-in-f105</ns1:name>
             </ns1:return>
          </ns1:getHostinfoResponse>
       	</soap:Body>
    </soap:Envelope>

## XML Types

This chapter bundles the documentation for common XML types used by XServices web service.

#### AntProperty type

The AntProperty type defines a list of key/value pairs.

The defining Java class is `net.brutex.xservices.types.AntProperty` .

    <xs:complexType name="antProperty">
       <xs:sequence>
          <xs:element name="name" type="xs:string"/>
          <xs:element name="value" type="xs:string"/>
       </xs:sequence>
    </xs:complexType>

    <AntProperty>
        <name>key2</name>
        <value>value2</value>
    </AntProperty>

#### FileResource type

The FileResource type defines an URI to a file with optional on-the-fly decompression.

The defining Java class is `net.brutex.xservices.types.FileResource` .

    <xs:complexType name="FileResourceType">
    	<xs:sequence>
        	<xs:element default="FILE" name="type" type="tns:type"/>
            <xs:element name="uri" type="xs:string"/>
       </xs:sequence>
    </xs:complexType>

Available types:

FILE: URI points to a local file resource. Examples: c:\temp\something.txt, c:/dir/another.file, /home/brian/file

URL: File from URL (http, https, ftp, ...). Example: http://brutex.net/file.pdf

GZIP and BZIP2: File from a local file system with on-the-fly decompression.

    <resource>
    	<type>FILE</type>
        <uri>c:\temp\xservices.war</uri>
    </resource>

#### HostConnection type

The HostConnection type identifies a server resource and login credentials.

The defining Java class is `net.brutex.xservices.types.HostConnection` .

Schema definition

    <xs:complexType name="connection">
       <xs:sequence>
          <xs:element name="hostname" type="xs:string"/>
          <xs:element name="port" type="xs:int"/>
          <xs:element minOccurs="0" name="user" type="xs:string"/>
          <xs:element minOccurs="0" name="password" type="xs:string"/>
       </xs:sequence>
    </xs:complexType>

Example XML

    <host>
       <hostname>server.brutex.net</hostname>
       <port>512</port> <!-- default rExec port -->
       <user>brian</user>
       <!--Optional:-->
       <password>somepass</password>
    </host>

#### PatternElement type

The PatternElement type defines single string pattern for file/ directory matching.

The defining Java class is `net.brutex.xservices.types.PatternElement` .

These patterns look exactly like those used in Apache Ant Patterns. The '*' matches zero or more characters and the '?' will match a single character. Both symbols can be combined in one pattern. The '**' symbol can be used to match any directory deepth.

Some example patterns:

`**/mydir/**`

Match all file that are located in any directory that has "mydir" string in its pathname. Also applies to files with "mydir" in their name.

`/mydir/`

The parser will automatically append an '**' symbol, thus the resulting pattern is `/mydir/**`. All files below the "/mydir/" directory (including its sub-directories will be chosen.

The pattern is OS independent. You should always use "/" as path separator, even on windows based systems.

Schema definition

    <xs:simpleType name="patternElement">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>

Example XML

    <PatternElement>**/*</PatternElement>

#### PatternSetType type

The PatternSetType exposes various filters/ selectors for the selection of resources (files).

The defining Java class is `net.brutex.xservices.types.PatternSetType` .

Schema definition

    <xs:complexType name="patternSetType">
        <xs:sequence>
            <xs:element default="**/*" maxOccurs="unbounded" minOccurs="0" name="include" type="tns:patternElement"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="exclude" type="tns:patternElement"/>
            <xs:element minOccurs="0" name="selector" nillable="true" type="tns:selectorType"/>
        </xs:sequence>
    </xs:complexType>

Example XML

                tbd.

#### ReturnCode type

The ReturnCode type is used as the generic answer type for most of the BruteXservices operations.

The defining Java class is `net.brutex.xservices.types.ReturnCode` .

Schema definition

    <xs:complexType name="ReturnCodeType">
        <xs:sequence>
            <xs:element name="returnCode" type="xs:int"/>
            <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
            <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
            <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="tns:antProperty"/>
        </xs:sequence>
    </xs:complexType>

Example XML

    		<ReturnCode
    		xmlns:ns2="http://ws.xservices.brutex.net">
    		<returnCode>0</returnCode>
    		<stdOut/>
    		<stdErr/>
    		<propertyList>

    			See
    			tns:antProperty
    			for details about the <propertyList> elements.

    		<name>key1</name>
    		<value>value1</value>
    		</propertyList>
    		<propertyList>
    		<name>key2</name>
    		<value>value2</value>
    		</propertyList>
    		</ReturnCode>

#### SelectorType type

The SelectorType exposes various selectors for the selection of resources (files).

The defining Java class is `net.brutex.xservices.types.SelectorType`.

Schema definition

             <xs:complexType abstract="true" name="selectorType">
                <xs:sequence>
                   <xs:element maxOccurs="unbounded" minOccurs="0" name="contains" nillable="true" type="tns:containsSelectorType"/>
                </xs:sequence>
             </xs:complexType>

Example XML

                tbd.