BruteXservices User Guide

Brian Rosenberger


Table of Contents

1. Abstract
2. Getting startet
Prerequisites
Installation
Securing BruteXservices with Basic Authentication
Limit access to BruteXservices
3. BruteXservices
ArchiveServices
ExecuteServices
runCommand
4. XML Types
ReturnCode type
Schema description
Example XML
AntProperty type
Schema description
Example XML
PatternElement type
Schema description
Example XML

List of Tables

3.1. runCommand input parameters

Chapter 1. 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).

BruteXservices 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.

BruteXservices 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 BruteXservices add Web Services (SOAP) wrapper around Apache Ant tasks (since XBridgeNG 2.0)

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

Chapter 2. Getting startet

This chapter describes the installation.

Prerequisites

tbd.

Sun Java SE 1.6.0

Apache Tomcat 6

Installation

tbd.

In short: Deploy .WAR file to Apache Tomcat

Securing BruteXservices 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 BruteXservices

Sometimes you'll only want to restrict access to BruteXservices to only specified host names or IP addresses. This way, only clients at those specified addresses can use the BruteXservices 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>).

Chapter 3. BruteXservices

ArchiveServices

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

ExecuteServices

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

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

Table 3.1. 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.

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 description
<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>

Chapter 4. XML Types

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

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 description

<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>

AntProperty type

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

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

Schema description

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

Example XML

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

PatternElement type

The PatternElement type defines single string pattern.

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

Schema description

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

Example XML

<PatternElement>**/*</PatternElement>