887 lines
31 KiB
Plaintext
887 lines
31 KiB
Plaintext
|
<?xml version="1.0" encoding="UTF-8"?><book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
|
||
|
|
<title>Brutex XServices Documentation</title>
|
||
|
|
<bookinfo>
|
||
|
|
<date>February, 16th 2010</date>
|
||
|
|
<author>
|
||
|
|
<firstname>Brian</firstname>
|
||
|
|
<surname>Rosenberger</surname>
|
||
|
|
<email>bru@brutex.de</email>
|
||
|
|
</author>
|
||
|
|
<corpname>Brutex Network</corpname>
|
||
|
|
<copyright>
|
||
|
|
<year>2011</year>
|
||
|
|
</copyright>
|
||
|
|
<legalnotice>
|
||
|
|
<para>
|
||
|
|
The copyright holders make no representation about the suitability
|
||
|
|
of this document for any purpose. It is provided
|
||
|
|
<quote>as is</quote>
|
||
|
|
without expressed or implied warranty.
|
||
|
|
</para>
|
||
|
|
</legalnotice>
|
||
|
|
<legalnotice>
|
||
|
|
<para>Apache Tomcat and Apache Ant are trademarks of the Apache
|
||
|
|
Software Foundation.</para>
|
||
|
|
</legalnotice>
|
||
|
|
<abstract xml:base="common/abstract.xml">
|
||
|
|
<title>Abstract</title>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>These are the major goals of the loosely coupled
|
||
|
|
integration
|
||
|
|
strategy which is in turn one essential idea of a
|
||
|
|
service-oriented
|
||
|
|
architecture (SOA).</para>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>is an add-on to XBridgeNG 2.0. It runs standalone or in
|
||
|
|
combination with XBridgeNG. Pure XBridgeNG has two
|
||
|
|
components:</para>
|
||
|
|
<para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem>
|
||
|
|
<para>XML Schema for item based data types (e.g. tickets
|
||
|
|
from a bug
|
||
|
|
tracker system or a database record)</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>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,
|
||
|
|
...)</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem>
|
||
|
|
<para>The add Web Services (SOAP) wrapper around Apache Ant
|
||
|
|
tasks
|
||
|
|
(since XBridgeNG 2.0)</para>
|
||
|
|
</listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
<para>The current focus is on file-based operations. do not
|
||
|
|
contain an
|
||
|
|
integration server or a process execution
|
||
|
|
engine.</para>
|
||
|
|
</abstract>
|
||
|
|
</bookinfo>
|
||
|
|
<chapter id="installation">
|
||
|
|
<beginpage/>
|
||
|
|
<title>Getting started</title>
|
||
|
|
<para>This chapter describes the installation.</para>
|
||
|
|
<section xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:base="common/installation.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
|
||
|
|
<section>
|
||
|
|
<title>Installation</title>
|
||
|
|
<para>tbd.</para>
|
||
|
|
<para>Sun Java SE 1.6.0</para>
|
||
|
|
<para>Apache Tomcat 7</para>
|
||
|
|
<para>tbd.</para>
|
||
|
|
<para>In short: Deploy .WAR file to Apache Tomcat</para>
|
||
|
|
<section>
|
||
|
|
<title>Securing with Basic Authentication</title>
|
||
|
|
<para>There is a quick guide explaining Basic Authentication for Tomcat here: <link xlink:href="http://oreilly.com/pub/a/java/archive/tomcat-tips.html?page=1">
|
||
|
|
http://oreilly.com/pub/a/java/archive/tomcat-tips.html?page=1</link>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Limit access to</title>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>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.</para>
|
||
|
|
<programlisting language="xml"><Context
|
||
|
|
path="/XService/ArchiveService"
|
||
|
|
...> <Valve
|
||
|
|
className="org.apache.catalina.valves.RemoteAddrValve"
|
||
|
|
allow="127.0.0.1" deny=""/> </Context>
|
||
|
|
</programlisting>
|
||
|
|
<para>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.
|
||
|
|
</para>
|
||
|
|
<para>The <context> element must be placed into the
|
||
|
|
server.xml
|
||
|
|
file (into <engine><host>).</para>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</chapter>
|
||
|
|
<chapter id="services">
|
||
|
|
<beginpage/>
|
||
|
|
<title>Available Services</title>
|
||
|
|
<para>List of available web services and their operations.</para>
|
||
|
|
<section id="archiveservices" version="5.0" xml:base="ArchiveServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ArchiveServices</title>
|
||
|
|
<para>The ArchiveService bundles file packing operations. Its
|
||
|
|
WSDL is
|
||
|
|
located at
|
||
|
|
http://server:port/XServices/ArchiveService?wsdl</para>
|
||
|
|
</section>
|
||
|
|
<section id="executeservices" version="5.0" xml:base="ExecuteServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ExecuteServices</title>
|
||
|
|
<para>The ExecuteService bundles local and remote command
|
||
|
|
execution operations. Its WSDL is located at
|
||
|
|
http://server:port/XServices/ExecuteService?wsdl</para>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/rExec.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>rExec
|
||
|
|
</title>
|
||
|
|
<para>provides remote execution facilities with authentication based on
|
||
|
|
user names and passwords.</para>
|
||
|
|
<section>
|
||
|
|
<title>Input parameters
|
||
|
|
</title>
|
||
|
|
<para/>
|
||
|
|
<table frame="all">
|
||
|
|
<title>rExec
|
||
|
|
input parameters
|
||
|
|
</title>
|
||
|
|
<tgroup cols="4">
|
||
|
|
<colspec colname="parameter" colnum="1"/>
|
||
|
|
<colspec colname="type" colnum="2"/>
|
||
|
|
<colspec colname="required" colnum="3"/>
|
||
|
|
<colspec colname="description" colnum="4"/>
|
||
|
|
<thead>
|
||
|
|
<row>
|
||
|
|
<entry>parameter</entry>
|
||
|
|
<entry>type</entry>
|
||
|
|
<entry>required</entry>
|
||
|
|
<entry>description</entry>
|
||
|
|
</row>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<row>
|
||
|
|
<entry>host</entry>
|
||
|
|
<entry>HostConnection</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>
|
||
|
|
Host where to execute the command. See
|
||
|
|
<link linkend="hostconnection">HostConnection</link>
|
||
|
|
.
|
||
|
|
</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>command</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>Any command including arguments</entry>
|
||
|
|
</row>
|
||
|
|
<row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
|
||
|
|
<entry>timeout</entry>
|
||
|
|
<entry>Long</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
|
||
|
|
</row>
|
||
|
|
</tbody>
|
||
|
|
</tgroup>
|
||
|
|
</table>
|
||
|
|
<para/>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Output parameters
|
||
|
|
</title>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ReturnCode type</title>
|
||
|
|
<para>
|
||
|
|
The ReturnCode type is used as the generic answer type for most of the
|
||
|
|
<application class="software">BruteXservices</application>
|
||
|
|
operations.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
|
||
|
|
<classname>net.brutex.xservices.types.ReturnCode</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<ReturnCode
|
||
|
|
xmlns:ns2="http://ws.xservices.brutex.net">
|
||
|
|
<returnCode>0</returnCode>
|
||
|
|
<stdOut/>
|
||
|
|
<stdErr/>
|
||
|
|
<propertyList>
|
||
|
|
<lineannotation>
|
||
|
|
See
|
||
|
|
<link linkend="antproperty">tns:antProperty</link>
|
||
|
|
for details about the <propertyList> elements.
|
||
|
|
</lineannotation>
|
||
|
|
<name>key1</name>
|
||
|
|
<value>value1</value>
|
||
|
|
</propertyList>
|
||
|
|
<propertyList>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</propertyList>
|
||
|
|
</ReturnCode>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/runCommand.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>runCommand</title>
|
||
|
|
<para>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.</para>
|
||
|
|
<section>
|
||
|
|
<title>Input parameters
|
||
|
|
</title>
|
||
|
|
<para/>
|
||
|
|
<table frame="all">
|
||
|
|
<title>runCommand input parameters</title>
|
||
|
|
<tgroup cols="4">
|
||
|
|
<colspec colname="parameter" colnum="1"/>
|
||
|
|
<colspec colname="type" colnum="2"/>
|
||
|
|
<colspec colname="required" colnum="3"/>
|
||
|
|
<colspec colname="description" colnum="4"/>
|
||
|
|
<thead>
|
||
|
|
<row>
|
||
|
|
<entry>parameter</entry>
|
||
|
|
<entry>type</entry>
|
||
|
|
<entry>required</entry>
|
||
|
|
<entry>description</entry>
|
||
|
|
</row>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<row>
|
||
|
|
<entry>executable</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Command to be run. The command may be specified with full
|
||
|
|
path using forward slash "/" as path separator.</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>argline</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>Any command line arguments</entry>
|
||
|
|
</row>
|
||
|
|
<row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
|
||
|
|
<entry>timeout</entry>
|
||
|
|
<entry>Long</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
|
||
|
|
</row>
|
||
|
|
</tbody>
|
||
|
|
</tgroup>
|
||
|
|
</table>
|
||
|
|
<para/>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Output parameters
|
||
|
|
</title>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ReturnCode type</title>
|
||
|
|
<para>
|
||
|
|
The ReturnCode type is used as the generic answer type for most of the
|
||
|
|
<application class="software">BruteXservices</application>
|
||
|
|
operations.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
|
||
|
|
<classname>net.brutex.xservices.types.ReturnCode</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<ReturnCode
|
||
|
|
xmlns:ns2="http://ws.xservices.brutex.net">
|
||
|
|
<returnCode>0</returnCode>
|
||
|
|
<stdOut/>
|
||
|
|
<stdErr/>
|
||
|
|
<propertyList>
|
||
|
|
<lineannotation>
|
||
|
|
See
|
||
|
|
<link linkend="antproperty">tns:antProperty</link>
|
||
|
|
for details about the <propertyList> elements.
|
||
|
|
</lineannotation>
|
||
|
|
<name>key1</name>
|
||
|
|
<value>value1</value>
|
||
|
|
</propertyList>
|
||
|
|
<propertyList>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</propertyList>
|
||
|
|
</ReturnCode>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/runCommandWithSSH.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>runCommandWithSSH</title>
|
||
|
|
<para>Executes a command through a SSH session.</para>
|
||
|
|
<section>
|
||
|
|
<title>Input parameters
|
||
|
|
</title>
|
||
|
|
<para/>
|
||
|
|
<table frame="all">
|
||
|
|
<title>runCommandWithSSH input parameters</title>
|
||
|
|
<tgroup cols="4">
|
||
|
|
<colspec colname="parameter" colnum="1"/>
|
||
|
|
<colspec colname="type" colnum="2"/>
|
||
|
|
<colspec colname="required" colnum="3"/>
|
||
|
|
<colspec colname="description" colnum="4"/>
|
||
|
|
<thead>
|
||
|
|
<row>
|
||
|
|
<entry>parameter</entry>
|
||
|
|
<entry>type</entry>
|
||
|
|
<entry>required</entry>
|
||
|
|
<entry>description</entry>
|
||
|
|
</row>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<row>
|
||
|
|
<entry>host</entry>
|
||
|
|
<entry>HostConnection</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>
|
||
|
|
Host to connect to (see:
|
||
|
|
<link linkend="hostconnection">tns:HostConnection</link>
|
||
|
|
)
|
||
|
|
</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>command</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>The command to execute.</entry>
|
||
|
|
</row>
|
||
|
|
<row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
|
||
|
|
<entry>timeout</entry>
|
||
|
|
<entry>Long</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
|
||
|
|
</row>
|
||
|
|
</tbody>
|
||
|
|
</tgroup>
|
||
|
|
</table>
|
||
|
|
<para/>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Output parameters
|
||
|
|
</title>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ReturnCode type</title>
|
||
|
|
<para>
|
||
|
|
The ReturnCode type is used as the generic answer type for most of the
|
||
|
|
<application class="software">BruteXservices</application>
|
||
|
|
operations.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
|
||
|
|
<classname>net.brutex.xservices.types.ReturnCode</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<ReturnCode
|
||
|
|
xmlns:ns2="http://ws.xservices.brutex.net">
|
||
|
|
<returnCode>0</returnCode>
|
||
|
|
<stdOut/>
|
||
|
|
<stdErr/>
|
||
|
|
<propertyList>
|
||
|
|
<lineannotation>
|
||
|
|
See
|
||
|
|
<link linkend="antproperty">tns:antProperty</link>
|
||
|
|
for details about the <propertyList> elements.
|
||
|
|
</lineannotation>
|
||
|
|
<name>key1</name>
|
||
|
|
<value>value1</value>
|
||
|
|
</propertyList>
|
||
|
|
<propertyList>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</propertyList>
|
||
|
|
</ReturnCode>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Sample Request:</title>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<![CDATA[
|
||
|
|
<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>
|
||
|
|
]]></programlisting>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/telnet.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>telnet</title>
|
||
|
|
<para>Runs a telnet session with an "expect shell" like behaviour.</para>
|
||
|
|
<section>
|
||
|
|
<title>Input parameters
|
||
|
|
</title>
|
||
|
|
<para/>
|
||
|
|
<table frame="all">
|
||
|
|
<title>telnet input parameters</title>
|
||
|
|
<tgroup cols="4">
|
||
|
|
<colspec colname="parameter" colnum="1"/>
|
||
|
|
<colspec colname="type" colnum="2"/>
|
||
|
|
<colspec colname="required" colnum="3"/>
|
||
|
|
<colspec colname="description" colnum="4"/>
|
||
|
|
<thead>
|
||
|
|
<row>
|
||
|
|
<entry>parameter</entry>
|
||
|
|
<entry>type</entry>
|
||
|
|
<entry>required</entry>
|
||
|
|
<entry>description</entry>
|
||
|
|
</row>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<row>
|
||
|
|
<entry>host</entry>
|
||
|
|
<entry>HostConnection</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Host to connect to (see: <link linkend="hostconnection">tns:HostConnection</link>)</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>prompt</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>The prompt string to expect after login. This is used to recognize when
|
||
|
|
the session is open.</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>command</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>The command to execute.</entry>
|
||
|
|
</row>
|
||
|
|
<row>
|
||
|
|
<entry>expect</entry>
|
||
|
|
<entry>String</entry>
|
||
|
|
<entry>No</entry>
|
||
|
|
<entry>The prompt to expect after the command has been executed successfully.</entry>
|
||
|
|
</row>
|
||
|
|
<row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
|
||
|
|
<entry>timeout</entry>
|
||
|
|
<entry>Long</entry>
|
||
|
|
<entry>Yes</entry>
|
||
|
|
<entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
|
||
|
|
</row>
|
||
|
|
</tbody>
|
||
|
|
</tgroup>
|
||
|
|
</table>
|
||
|
|
<para/>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Output parameters</title>
|
||
|
|
<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ReturnCode type</title>
|
||
|
|
<para>
|
||
|
|
The ReturnCode type is used as the generic answer type for most of the
|
||
|
|
<application class="software">BruteXservices</application>
|
||
|
|
operations.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
|
||
|
|
<classname>net.brutex.xservices.types.ReturnCode</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<ReturnCode
|
||
|
|
xmlns:ns2="http://ws.xservices.brutex.net">
|
||
|
|
<returnCode>0</returnCode>
|
||
|
|
<stdOut/>
|
||
|
|
<stdErr/>
|
||
|
|
<propertyList>
|
||
|
|
<lineannotation>
|
||
|
|
See
|
||
|
|
<link linkend="antproperty">tns:antProperty</link>
|
||
|
|
for details about the <propertyList> elements.
|
||
|
|
</lineannotation>
|
||
|
|
<name>key1</name>
|
||
|
|
<value>value1</value>
|
||
|
|
</propertyList>
|
||
|
|
<propertyList>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</propertyList>
|
||
|
|
</ReturnCode>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section>
|
||
|
|
<title>Sample Request:</title>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<![CDATA[
|
||
|
|
<ws:telnet>
|
||
|
|
<host>
|
||
|
|
<hostname>localhost</hostname>
|
||
|
|
<port>23</port>
|
||
|
|
<user>brosenberger</user>
|
||
|
|
<password></password>
|
||
|
|
</host>
|
||
|
|
<prompt>C:\Users\brosenberger></prompt>
|
||
|
|
<command>dir c:\temp</command>
|
||
|
|
<expect>enberger></expect>
|
||
|
|
<timeout>60000</timeout>
|
||
|
|
</ws:telnet>
|
||
|
|
]]></programlisting>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
<section id="fileservices" version="5.0" xml:base="FileServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>FileServices</title>
|
||
|
|
<para>The FileServces bundles various file operations. Its WSDL is located at
|
||
|
|
http://server:port/XServices/FileService?wsdl</para>
|
||
|
|
</section>
|
||
|
|
<section id="miscservices" version="5.0" xml:base="MiscServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>MiscServices</title>
|
||
|
|
<para>The MiscService bundles various operations. Its WSDL is located at
|
||
|
|
http://server:port/XServices/MiscService?wsdl</para>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<chapter id="xmltypes">
|
||
|
|
<beginpage/>
|
||
|
|
<title>XML Types</title>
|
||
|
|
<para>This chapter bundles the documentation for common XML types used
|
||
|
|
by XServices web service.</para>
|
||
|
|
<section version="5.0" xml:base="Types.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<!-- Sort alphabetically -->
|
||
|
|
<section xml:base="types/AntProperty.xml">
|
||
|
|
<title>AntProperty type</title>
|
||
|
|
<para>The AntProperty type defines a list of key/value pairs.</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/AntProperty.html">
|
||
|
|
<classname>net.brutex.xservices.types.AntProperty</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<xs:complexType name="antProperty">
|
||
|
|
<xs:sequence>
|
||
|
|
<xs:element name="name" type="xs:string"/>
|
||
|
|
<xs:element name="value" type="xs:string"/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<AntProperty>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</AntProperty>]]>
|
||
|
|
</programlisting>
|
||
|
|
</section>
|
||
|
|
<section xml:base="types/FileResource.xml">
|
||
|
|
<title>FileResource type</title>
|
||
|
|
<para>The FileResource type defines an URI to a file with optional on-the-fly decompression.</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/FileResource.html">
|
||
|
|
<classname>net.brutex.xservices.types.FileResource</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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>]]>
|
||
|
|
</programlisting>
|
||
|
|
<para>Available types:</para>
|
||
|
|
<para>FILE: URI points to a local file resource. Examples: c:\temp\something.txt, c:/dir/another.file, /home/brian/file</para>
|
||
|
|
<para>URL: File from URL (http, https, ftp, ...). Example: http://brutex.net/file.pdf</para>
|
||
|
|
<para>GZIP and BZIP2: File from a local file system with on-the-fly decompression.</para>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<resource>
|
||
|
|
<type>FILE</type>
|
||
|
|
<uri>c:\temp\xservices.war</uri>
|
||
|
|
</resource>]]>
|
||
|
|
</programlisting>
|
||
|
|
</section>
|
||
|
|
<section id="hostconnection" version="5.0" xml:base="types/HostConnection.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>HostConnection type</title>
|
||
|
|
<para>The HostConnection type identifies a server resource and login
|
||
|
|
credentials.</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/HostConnection.html">
|
||
|
|
<classname>net.brutex.xservices.types.HostConnection</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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>
|
||
|
|
]]>
|
||
|
|
</programlisting>
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<host>
|
||
|
|
<hostname>server.brutex.net</hostname>
|
||
|
|
<port>512</port> <!-- default rExec port -->
|
||
|
|
<user>brian</user>
|
||
|
|
<!--Optional:-->
|
||
|
|
<password>somepass</password>
|
||
|
|
</host>
|
||
|
|
]]>
|
||
|
|
</programlisting>
|
||
|
|
</section>
|
||
|
|
<section id="patternelement" version="5.0" xml:base="types/PatternElement.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>PatternElement type</title>
|
||
|
|
<para>The PatternElement type defines single string pattern for file/
|
||
|
|
directory matching.</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/PatternElement.html">
|
||
|
|
<classname>net.brutex.xservices.types.PatternElement</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
These patterns look exactly like those used in Apache Ant
|
||
|
|
<ulink url="http://ant.apache.org/manual/dirtasks.html#patterns">Patterns</ulink>.
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
<para>Some example patterns:</para>
|
||
|
|
<para>
|
||
|
|
<parameter>**/mydir/**</parameter>
|
||
|
|
</para>
|
||
|
|
<para>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.</para>
|
||
|
|
<para>
|
||
|
|
<parameter>/mydir/</parameter>
|
||
|
|
</para>
|
||
|
|
<para>The
|
||
|
|
parser will automatically append an '**' symbol, thus the
|
||
|
|
resulting pattern is
|
||
|
|
<parameter>/mydir/**</parameter>.
|
||
|
|
All files below the "/mydir/" directory (including its
|
||
|
|
sub-directories will be chosen.
|
||
|
|
</para>
|
||
|
|
<note>
|
||
|
|
<para>The pattern is OS independent. You should always use
|
||
|
|
"/" as path separator, even on windows based systems.
|
||
|
|
</para>
|
||
|
|
</note>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[<xs:simpleType name="patternElement">
|
||
|
|
<xs:restriction base="xs:string"/>
|
||
|
|
</xs:simpleType>]]></programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[<PatternElement>**/*</PatternElement>]]></programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
<section id="patternsettype" version="5.0" xml:base="types/PatternSetType.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>PatternSetType type</title>
|
||
|
|
<para>The PatternSetType exposes various filters/ selectors for the
|
||
|
|
selection of resources (files).</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/PatternSetType.html">
|
||
|
|
<classname>net.brutex.xservices.types.PatternSetType</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<xs:complexType name="patternSetType">
|
||
|
|
<xs:sequence>
|
||
|
|
<xs:element default="**/*" maxOccurs="unbounded" minOccurs="0" name="include" type="]]><link linkend="patternelement">tns:patternElement</link><![CDATA["/>
|
||
|
|
<xs:element maxOccurs="unbounded" minOccurs="0" name="exclude" type="]]><link linkend="patternelement">tns:patternElement</link><![CDATA["/>
|
||
|
|
<xs:element minOccurs="0" name="selector" nillable="true" type="]]><link linkend="selectortype">tns:selectorType</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
tbd.]]>
|
||
|
|
</programlisting>
|
||
|
|
</section>
|
||
|
|
<section version="5.0" xml:base="types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>ReturnCode type</title>
|
||
|
|
<para>
|
||
|
|
The ReturnCode type is used as the generic answer type for most of the
|
||
|
|
<application class="software">BruteXservices</application>
|
||
|
|
operations.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
|
||
|
|
<classname>net.brutex.xservices.types.ReturnCode</classname>
|
||
|
|
</ulink>
|
||
|
|
.
|
||
|
|
</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>]]>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml">
|
||
|
|
<ReturnCode
|
||
|
|
xmlns:ns2="http://ws.xservices.brutex.net">
|
||
|
|
<returnCode>0</returnCode>
|
||
|
|
<stdOut/>
|
||
|
|
<stdErr/>
|
||
|
|
<propertyList>
|
||
|
|
<lineannotation>
|
||
|
|
See
|
||
|
|
<link linkend="antproperty">tns:antProperty</link>
|
||
|
|
for details about the <propertyList> elements.
|
||
|
|
</lineannotation>
|
||
|
|
<name>key1</name>
|
||
|
|
<value>value1</value>
|
||
|
|
</propertyList>
|
||
|
|
<propertyList>
|
||
|
|
<name>key2</name>
|
||
|
|
<value>value2</value>
|
||
|
|
</propertyList>
|
||
|
|
</ReturnCode>
|
||
|
|
</programlisting>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
<section id="selectortype" version="5.0" xml:base="types/SelectorType.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
|
<title>SelectorType type</title>
|
||
|
|
<para>The SelectorType exposes various selectors for the selection of resources (files).</para>
|
||
|
|
<para>The defining Java class is
|
||
|
|
<ulink url="javadoc/net/brutex/xservices/types/SelectorType.html">
|
||
|
|
<classname>net.brutex.xservices.types.SelectorType</classname></ulink>.</para>
|
||
|
|
<bridgehead renderas="sect3">Schema definition</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
<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>]]>
|
||
|
|
</programlisting>
|
||
|
|
<bridgehead renderas="sect3">Example XML</bridgehead>
|
||
|
|
<programlisting language="xml"><![CDATA[
|
||
|
|
tbd.]]>
|
||
|
|
</programlisting>
|
||
|
|
</section>
|
||
|
|
</section>
|
||
|
|
</chapter>
|
||
|
|
</book>
|