From 812e24bec23707ddc93ed072bbfbd0273d00248d Mon Sep 17 00:00:00 2001 From: Brian Rosenberger Date: Tue, 16 Feb 2010 11:20:25 +0000 Subject: [PATCH] Moving to docbook style documentation git-svn-id: https://brutex.net/svn/xservices/trunk@25 e7e49efb-446e-492e-b9ec-fcafc1997a86 --- ...buch.xml => BruteXServices_User_Guide.xml} | 16 +- doc/ExecuteServices/runCommand.xml | 2 +- doc/Types.xml | 2 +- doc/abstract.xml | 39 +- doc/buch.html | 361 ------------------ doc/entities.ent | 7 + doc/getting-started.xml | 2 +- doc/types/AntProperty.xml | 9 +- doc/types/PatternElement.xml | 46 ++- doc/types/PatternSetType.xml | 23 ++ doc/types/ReturnCode.xml | 22 +- doc/types/SelectorType.xml | 20 + 12 files changed, 128 insertions(+), 421 deletions(-) rename doc/{buch.xml => BruteXServices_User_Guide.xml} (60%) delete mode 100644 doc/buch.html create mode 100644 doc/types/PatternSetType.xml create mode 100644 doc/types/SelectorType.xml diff --git a/doc/buch.xml b/doc/BruteXServices_User_Guide.xml similarity index 60% rename from doc/buch.xml rename to doc/BruteXServices_User_Guide.xml index c6582fb..e6019c9 100644 --- a/doc/buch.xml +++ b/doc/BruteXServices_User_Guide.xml @@ -13,14 +13,28 @@ &brs; User Guide + February, 16th 2010 Brian Rosenberger bru@brutex.de Brutex Network + 1997 2010 + + 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; -&abstract;&getting-started;&xservices;&types; +&getting-started;&xservices;&types; diff --git a/doc/ExecuteServices/runCommand.xml b/doc/ExecuteServices/runCommand.xml index a9a4b85..11b8a91 100644 --- a/doc/ExecuteServices/runCommand.xml +++ b/doc/ExecuteServices/runCommand.xml @@ -24,7 +24,7 @@ executable String Yes - Command to be run. The command may be specified with full path using forward slash “/” as path separator. + Command to be run. The command may be specified with full path using forward slash "/" as path separator. argline diff --git a/doc/Types.xml b/doc/Types.xml index 9a9f1b7..2874d56 100644 --- a/doc/Types.xml +++ b/doc/Types.xml @@ -1,4 +1,4 @@ XML Types This chapter bundles the documentation for common xml types used by XServices web service. -&returncode;&antproperty;&patternelement; \ No newline at end of file +&returncode;&patternsettype;&selectortype;&antproperty;&patternelement; \ No newline at end of file diff --git a/doc/abstract.xml b/doc/abstract.xml index 0985d03..b09a9df 100644 --- a/doc/abstract.xml +++ b/doc/abstract.xml @@ -1,21 +1,20 @@ - - 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). - &brs; 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. - &brs; 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, …) + +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). +&brs; 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. +&brs; 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 &brs; add + Web Services (SOAP) wrapper around Apache Ant tasks (since XBridgeNG 2.0) + + - - - The &brs; add - Web Services (SOAP) wrapper around Apache Ant tasks (since XBridgeNG 2.0) - - - The current focus is on file-based operations. &brs; do not contain an integration server or a process execution engine. - \ No newline at end of file +The current focus is on file-based operations. &brs; do not contain an integration server or a process execution engine. diff --git a/doc/buch.html b/doc/buch.html deleted file mode 100644 index cd6a1bd..0000000 --- a/doc/buch.html +++ /dev/null @@ -1,361 +0,0 @@ - - - -BruteXservices User Guide - - -
-
-
-

-BruteXservices User Guide

-
-

-Brian Rosenberger -

- -
-

Copyright 2010

-
-
-
-
-

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

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

-
-
-

-Chapter2.Getting startet

-
-

Table of Contents

-
-
Prerequisites
-
Installation
-
-
Securing BruteXservices with Basic Authentication
-
Limit access to BruteXservices
-
-
-
-

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

-
-
-
-
-

-Chapter3.BruteXservices -

-
-

Table of Contents

-
-
ArchiveServices
-
ExecuteServices
-
runCommand
-
-
-
-

-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

-

-
-

Table3.1.runCommand input parameters

- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - -
parametertyperequireddescription
executableStringYesCommand to be run. The command may be specified with full path using forward slash “/” as path separator.
arglineStringNoAny command line arguments
timeoutLongYesTimeout 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>
-
-
-
-
-
-
-
-

-Chapter4.XML Types

-
-

Table of Contents

-
-
ReturnCode type
-
-
Schema description
-
Example XML
-
-
AntProperty type
-
-
Schema description
-
Example XML
-
-
PatternElement type
-
-
Schema description
-
Example XML
-
-
-
-

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>
-
-
-
-
-
- diff --git a/doc/entities.ent b/doc/entities.ent index 0f02a9c..15bf21a 100644 --- a/doc/entities.ent +++ b/doc/entities.ent @@ -7,7 +7,14 @@ Yes Timeout in milliseconds. The command is forcefully terminated when timeout is reached. "> + +Example XML"> +Schema definition"> + + + + diff --git a/doc/getting-started.xml b/doc/getting-started.xml index fbf0648..20aaabe 100644 --- a/doc/getting-started.xml +++ b/doc/getting-started.xml @@ -1,6 +1,6 @@ - Getting startet + Getting started This chapter describes the installation. Prerequisites diff --git a/doc/types/AntProperty.xml b/doc/types/AntProperty.xml index 5fc320c..c10576e 100644 --- a/doc/types/AntProperty.xml +++ b/doc/types/AntProperty.xml @@ -4,8 +4,7 @@ The defining Java class is net.brutex.xservices.types.AntProperty. -
- Schema description +&schemadefinition; @@ -14,14 +13,12 @@ ]]> -
-
- Example XML +&examplexml; key2 value2 ]]> -
+ \ No newline at end of file diff --git a/doc/types/PatternElement.xml b/doc/types/PatternElement.xml index f66ead6..1c26425 100644 --- a/doc/types/PatternElement.xml +++ b/doc/types/PatternElement.xml @@ -1,21 +1,31 @@
- PatternElement type - The PatternElement type defines single string pattern. - The defining Java class is - - net.brutex.xservices.types.PatternElement. -
- Schema description - + 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. + + &schemadefinition; + -]]> - -
-
- Example XML - **/*]]> - -
+]]> + +&examplexml; + **/*]]> +
\ No newline at end of file diff --git a/doc/types/PatternSetType.xml b/doc/types/PatternSetType.xml new file mode 100644 index 0000000..59bbabb --- /dev/null +++ b/doc/types/PatternSetType.xml @@ -0,0 +1,23 @@ + +
+ PatternSetType type + The PatternSetType exposes various filters/ selectors for the selection of resources (files). + The defining Java class is + + net.brutex.xservices.types.PatternSetType. + &schemadefinition; + + + tns:patternElement + tns:patternElement + tns:selectorType + +]]> + +&examplexml; + + +
+ diff --git a/doc/types/ReturnCode.xml b/doc/types/ReturnCode.xml index 555bc52..94560f2 100644 --- a/doc/types/ReturnCode.xml +++ b/doc/types/ReturnCode.xml @@ -2,23 +2,21 @@ ReturnCode type The ReturnCode type is used as the generic answer type for most of the &brs; operations. The defining Java class is - + net.brutex.xservices.types.ReturnCode. -
- Schema description +&schemadefinition; - - - - tns:antProperty + + + + tns:antProperty - ]]> +]]> -
-
- Example XML + +&examplexml; <ReturnCode xmlns:ns2="http://ws.xservices.brutex.net"> <returnCode>0</returnCode> <stdOut/> @@ -32,5 +30,5 @@ <value>value2</value> </propertyList> </ReturnCode> -
+ \ No newline at end of file diff --git a/doc/types/SelectorType.xml b/doc/types/SelectorType.xml new file mode 100644 index 0000000..20d9b52 --- /dev/null +++ b/doc/types/SelectorType.xml @@ -0,0 +1,20 @@ + +
+ SelectorType type + The SelectorType exposes various selectors for the selection of resources (files). + The defining Java class is + + net.brutex.xservices.types.SelectorType. +&schemadefinition; + + + + + ]]> + +&examplexml; + + +