XServices/doc/BruteXServices_User_Guide.xml

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
  <title>User Guide</title>
  <bookinfo>
    <date>February, 16th 2010</date>
    <author>
      <firstname>Brian</firstname>
      <surname>Rosenberger</surname>
      <email>bru@brutex.de</email>
    </author>
    <corpname>Brutex Network</corpname>
    <pubdate>1997</pubdate>
    <copyright><year>2010</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>
      <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>
    <beginpage />
    <title>Getting started</title>
    <para>This chapter describes the installation.</para>
    <sect1>
      <title>Prerequisites</title>
      <para>tbd.</para>
      <para>Sun Java SE 1.6.0</para>
      <para>Apache Tomcat 6</para>
    </sect1>
    <sect1>
      <title>Installation</title>
      <para>tbd.</para>
      <para>In short: Deploy .WAR file to Apache Tomcat</para>
      <sect2>
        <title>Securing with Basic Authentication</title>
        <para>There is a quick guide explaining Basic Authentication 
        for Tomcat here:</para>
        <para>
        <ulink url="http://oreilly.com/pub/a/java/archive/tomcat-tips.html?page=1"/></para>
      </sect2>
      <sect2>
        <title>Limit access to</title>
        <para>Sometimes you&apos;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">&lt;Context path=&quot;/XService/ArchiveService&quot; ...&gt;
                &lt;Valve className=&quot;org.apache.catalina.valves.RemoteAddrValve&quot;
                allow=&quot;127.0.0.1&quot; deny=&quot;&quot;/&gt;
            &lt;/Context&gt;</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 &lt;context&gt; element must be placed into the 
        server.xml file (into &lt;engine&gt;&lt;host&gt;).</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter>
    <title />
    <section>
      <title>ArchiveServices</title>
      <para>The ArchiveService bundles file packing operations. Its 
      WSDL is located at 
      http://server:port/XServices/ArchiveService?wsdl</para>
    </section>
    <section>
      <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>
        <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 />
          <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 
                  &quot;/&quot; as path separator.</entry>
                </row>
                <row>
                  <entry>argline</entry>
                  <entry>String</entry>
                  <entry>No</entry>
                  <entry>Any command line arguments</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <para />
        </section>
      </section>
    </section>
  </chapter>
  <chapter>
    <title>XML Types</title>
    <para>This chapter bundles the documentation for common xml types 
    used by XServices web service.</para>
  </chapter>
</book>