From 1474ad85896d215384aaeaa865ba1e1f7e5220a2 Mon Sep 17 00:00:00 2001 From: Brian Rosenberger Date: Thu, 19 May 2011 15:28:13 +0000 Subject: [PATCH] Tidy Up FileService implementation and add more javadoc information git-svn-id: https://brutex.net/svn/xservices/trunk@64 e7e49efb-446e-492e-b9ec-fcafc1997a86 --- BruteXServices_User_Guide.html | 207 ++++ doc/html/executeservices.html | 210 ++++ doc/html/fileservices.html | 2 + doc/html/index.html | 48 + doc/html/installation.html | 34 + doc/html/miscservices.html | 2 + doc/html/services.html | 5 + doc/html/xmltypes.html | 160 +++ .../xservices/util/BrutexNamespaces.java | 21 +- .../util/XServicesDocumentation.java | 65 ++ .../net/brutex/xservices/ws/FileService.java | 121 ++- .../xservices/ws/impl/FileServiceImpl.java | 80 +- test/ArchiveService-soapui-project.xml | 521 ++++++++++ test/ExecuteService-soapui-project.xml | 21 + test/FileServiceMTOM-soapui-project.xml | 950 +++++++++--------- test/MiscService-soapui-project.xml | 322 ++++++ 16 files changed, 2248 insertions(+), 521 deletions(-) create mode 100644 BruteXServices_User_Guide.html create mode 100644 doc/html/executeservices.html create mode 100644 doc/html/fileservices.html create mode 100644 doc/html/index.html create mode 100644 doc/html/installation.html create mode 100644 doc/html/miscservices.html create mode 100644 doc/html/services.html create mode 100644 doc/html/xmltypes.html create mode 100644 src/java/net/brutex/xservices/util/XServicesDocumentation.java create mode 100644 test/ArchiveService-soapui-project.xml create mode 100644 test/ExecuteService-soapui-project.xml create mode 100644 test/MiscService-soapui-project.xml diff --git a/BruteXServices_User_Guide.html b/BruteXServices_User_Guide.html new file mode 100644 index 0000000..d4ead48 --- /dev/null +++ b/BruteXServices_User_Guide.html @@ -0,0 +1,207 @@ +User Guide

User Guide

Brian Rosenberger

+

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

+

1997

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.

+

List of Tables

2.1. runCommand input parameters
+ + +

Chapter 1. Getting started

+ + +

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

+
+
+
+

Chapter 2. 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

+
+
+

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.

+
+ +

+

Table 2.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
+

+

+
+
+
+
+
+ +

Chapter 3. XML Types

Table of Contents

AntProperty type
+ + +

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>
+			
+
+
+
\ No newline at end of file diff --git a/doc/html/executeservices.html b/doc/html/executeservices.html new file mode 100644 index 0000000..50e3e30 --- /dev/null +++ b/doc/html/executeservices.html @@ -0,0 +1,210 @@ +ExecuteServices

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 +

Table 2.1. rExec + input parameters +

parametertyperequireddescription
hostHostConnectionYes + Host where to execute the command. See + HostConnection + . +
commandStringNoAny command including arguments
timeoutLongYesTimeout 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 +

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

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 +

Table 2.3. runCommandWithSSH input parameters

parametertyperequireddescription
hostHostConnectionYes + Host to connect to (see: + tns:HostConnection + ) +
commandStringNoThe command to execute.
timeoutLongYesTimeout 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 +

Table 2.4. telnet input parameters

parametertyperequireddescription
hostHostConnectionYesHost to connect to (see: tns:HostConnection)
promptStringNoThe prompt string to expect after login. This is used to recognize when + the session is open.
commandStringNoThe command to execute.
expectStringNoThe prompt to expect after the command has been executed successfully.
timeoutLongYesTimeout 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>
+	
\ No newline at end of file diff --git a/doc/html/fileservices.html b/doc/html/fileservices.html new file mode 100644 index 0000000..2ede712 --- /dev/null +++ b/doc/html/fileservices.html @@ -0,0 +1,2 @@ +FileServices

FileServices

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

\ No newline at end of file diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..3d60e45 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,48 @@ +Brutex XServices Documentation

Brutex XServices Documentation

Brian Rosenberger

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


\ No newline at end of file diff --git a/doc/html/installation.html b/doc/html/installation.html new file mode 100644 index 0000000..c0427b2 --- /dev/null +++ b/doc/html/installation.html @@ -0,0 +1,34 @@ +Chapter 1. Getting started

Chapter 1. Getting started

Table of Contents

Installation

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

\ No newline at end of file diff --git a/doc/html/miscservices.html b/doc/html/miscservices.html new file mode 100644 index 0000000..aa3aaf2 --- /dev/null +++ b/doc/html/miscservices.html @@ -0,0 +1,2 @@ +MiscServices

MiscServices

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

\ No newline at end of file diff --git a/doc/html/services.html b/doc/html/services.html new file mode 100644 index 0000000..ad35509 --- /dev/null +++ b/doc/html/services.html @@ -0,0 +1,5 @@ +Chapter 2. Available Services

Chapter 2. 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

\ No newline at end of file diff --git a/doc/html/xmltypes.html b/doc/html/xmltypes.html new file mode 100644 index 0000000..5e139d1 --- /dev/null +++ b/doc/html/xmltypes.html @@ -0,0 +1,160 @@ +Chapter 3. XML Types

Chapter 3. 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. +

[Note]Note

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.
+        
\ No newline at end of file diff --git a/src/java/net/brutex/xservices/util/BrutexNamespaces.java b/src/java/net/brutex/xservices/util/BrutexNamespaces.java index e45671d..d821047 100644 --- a/src/java/net/brutex/xservices/util/BrutexNamespaces.java +++ b/src/java/net/brutex/xservices/util/BrutexNamespaces.java @@ -26,9 +26,28 @@ public class BrutexNamespaces { /** - * Brutex Network XServices web service namespace declaration + * Brutex Network XServices web service name space declaration */ public static final String WS_XSERVICES = "http://ws.xservices.brutex.net"; + /** + * Copyright and license agreement statement. + */ + public static final String BRUTEX_COPYRIGHT = "" + + "/*\n" + + "* Copyright 2010 Brian Rosenberger (Brutex Network)\n" + + "*\n" + + "* Licensed under the Apache License, Version 2.0 (the \"License\")\n" + + "* you may not use this file except in compliance with the License.\n" + + "* You may obtain a copy of the License at\n" + + "*\n" + + "* http://www.apache.org/licenses/LICENSE-2.0\n" + + "*\n" + + "* Unless required by applicable law or agreed to in writing, software\n" + + "* distributed under the License is distributed on an \"AS IS\" BASIS,\n" + + "* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" + + "* See the License for the specific language governing permissions and\n" + + "* limitations under the License.\n" + + "*/"; private BrutexNamespaces() {}; diff --git a/src/java/net/brutex/xservices/util/XServicesDocumentation.java b/src/java/net/brutex/xservices/util/XServicesDocumentation.java new file mode 100644 index 0000000..474f6d5 --- /dev/null +++ b/src/java/net/brutex/xservices/util/XServicesDocumentation.java @@ -0,0 +1,65 @@ +/* + * Copyright 2011 Brian Rosenberger (Brutex Network) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package net.brutex.xservices.util; + +/** + * Holds static documentation. + * + * + * @author Brian Rosenberger, bru@brutex.de + */ +public class XServicesDocumentation { + + + public static final String BRUTEX_COPYRIGHT = "" + + "/*\n" + + "* Copyright 2010 Brian Rosenberger (Brutex Network)\n" + + "*\n" + + "* Licensed under the Apache License, Version 2.0 (the \"License\")\n" + + "* you may not use this file except in compliance with the License.\n" + + "* You may obtain a copy of the License at\n" + + "*\n" + + "* http://www.apache.org/licenses/LICENSE-2.0\n" + + "*\n" + + "* Unless required by applicable law or agreed to in writing, software\n" + + "* distributed under the License is distributed on an \"AS IS\" BASIS,\n" + + "* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" + + "* See the License for the specific language governing permissions and\n" + + "* limitations under the License.\n" + + "*/"; + + + public static final String SERVICE_OPERATION_DOWNLOADFILE = "Download a file from the maschine where the service is running in order " + + "to process it with the client. The file is either downloaded as a MTOM attachment or " + + "as inline base64 encoded block. Keep in mind that unless you are using MTOM, a lot of " + + "java heap memory is used."; + + public static final String SERVICE_OPERATION_UPLOADFILE = "Send a file from client to web service server using either " + + "MTOM attachment or base64 inline attachment."; + + public static final String SERVICE_OPERATION_COPY = "Copies a fileset locally on the server."; + + public static final String SERVICE_OPERATION_COPYFILE = "Copies a single file locally on the server"; + + public static final String SERVICE_OPERATION_LOADRESOURCE = "Load the content of a resource"; + + public static final String SERVICE_OPERATION_LOADRESOURCEFROMARCHIVE = "Load the content of a resource"; + + public static final String SERVICE_OPERATION_ECHOTOFILE = "Write or append a string to a file"; + + private XServicesDocumentation() {}; +} diff --git a/src/java/net/brutex/xservices/ws/FileService.java b/src/java/net/brutex/xservices/ws/FileService.java index 0420edd..2f8dc16 100644 --- a/src/java/net/brutex/xservices/ws/FileService.java +++ b/src/java/net/brutex/xservices/ws/FileService.java @@ -1,11 +1,32 @@ +/* + * Copyright 2010 Brian Rosenberger (Brutex Network) + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + package net.brutex.xservices.ws; import java.util.List; -import javax.activation.DataHandler; import javax.jws.WebMethod; import javax.jws.WebParam; import javax.jws.WebService; +import javax.xml.bind.annotation.XmlElement; + +import org.apache.cxf.annotations.WSDLDocumentation; +import org.apache.cxf.annotations.WSDLDocumentationCollection; + +import com.sun.xml.internal.ws.api.model.wsdl.WSDLDescriptorKind; import net.brutex.xservices.types.ArchiveResource; import net.brutex.xservices.types.AttachmentType; @@ -14,67 +35,137 @@ import net.brutex.xservices.types.FileSetResource; import net.brutex.xservices.types.ReplacePattern; import net.brutex.xservices.types.ReturnCode; import net.brutex.xservices.util.BrutexNamespaces; +import net.brutex.xservices.util.XServicesDocumentation; +/** + * @author Brian Rosenberger + * + */ @WebService(targetNamespace = BrutexNamespaces.WS_XSERVICES) +@WSDLDocumentationCollection( + { + @WSDLDocumentation(value = BrutexNamespaces.BRUTEX_COPYRIGHT, placement = WSDLDocumentation.Placement.TOP) + } +) public interface FileService { + /** + * @param filename + * @param suffix + * @return The base name of the given file excluding the suffix. + */ + @WSDLDocumentation(value = "The base name of the given file excluding the suffix.") @WebMethod(operationName = "basename") - public abstract ReturnCode basename( - @WebParam(name = "file") String filename, + public abstract String basename( + @WebParam(name = "file") @XmlElement(required=true) String filename, @WebParam(name = "suffix") String suffix); + /** + * @param res + * @return The file itself (MTOM attachment or inline base64) including some file metadata. + */ + @WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_DOWNLOADFILE) @WebMethod(operationName = "downloadFile") public abstract AttachmentType downloadFile( @WebParam(name = "file") FileResource res); + /** + * @param file + * @return The file name of the file that has been uploaded. + */ + @WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_UPLOADFILE) @WebMethod(operationName = "uploadFile") public abstract String uploadFile( @WebParam(name = "file") AttachmentType file); + /** + * @param src + * @param todir + * @param plm + * @param overwrite + * @param encoding + * @return + * @throws XServicesFault + */ + @WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPY) @WebMethod(operationName = "copy") public abstract ReturnCode copy( - @WebParam(name = "fileset") FileSetResource src, - @WebParam(name = "todir") String todir, + @WebParam(name = "fileset") @XmlElement(required=true) FileSetResource src, + @WebParam(name = "todir") @XmlElement(required=true) String todir, @WebParam(name = "preservelastmodified") boolean plm, @WebParam(name = "overwrite") boolean overwrite, @WebParam(name = "encoding") String encoding) throws XServicesFault; + + /** + * @param fromFile + * @param tofile + * @param overwrite + * @return + * @throws XServicesFault + */ + @WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPYFILE) + @WebMethod(operationName = "copyFile") + public abstract ReturnCode copyFile( + @WebParam(name = "fromFile") @XmlElement(required=true) String fromFile, + @WebParam(name = "toFile") @XmlElement(required=true) String tofile, + @WebParam(name = "overwrite") boolean overwrite) throws XServicesFault; + /** + * @param res + * @param encoding + * @return content of the resource + */ + @WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCE) @WebMethod(operationName = "loadResource") - public abstract ReturnCode loadRes( + public abstract String loadRes( @WebParam(name = "resource") FileResource res, @WebParam(name = "encoding") String encoding); + /** + * @param res + * @param encoding + * @return content of the resource + */ + @WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCEFROMARCHIVE) @WebMethod(operationName = "loadResourceFromArchive") - public abstract ReturnCode loadResFromArchive( + public abstract String loadResFromArchive( @WebParam(name = "archiveresource") ArchiveResource res, @WebParam(name = "encoding") String encoding); + /** + * @param message + * @param file + * @param encoding + * @param append + * @return + */ + @WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_ECHOTOFILE) @WebMethod(operationName = "echoToFile") public abstract ReturnCode echo2file( - @WebParam(name = "message") String message, - @WebParam(name = "file") String file, + @WebParam(name = "message") @XmlElement(required=true) String message, + @WebParam(name = "file") @XmlElement(required=true) String file, @WebParam(name = "encoding") String encoding, @WebParam(name = "append") boolean append); @WebMethod(operationName = "changeOwner") public abstract ReturnCode changeOwner( @WebParam(name = "fileset") FileSetResource res, - @WebParam(name = "owner") String owner); + @WebParam(name = "owner") @XmlElement(required=true) String owner); @WebMethod(operationName = "changeGroup") public abstract ReturnCode changeGroup( @WebParam(name = "fileset") FileSetResource res, - @WebParam(name = "group") String group); + @WebParam(name = "group") @XmlElement(required=true) String group); @WebMethod(operationName = "changeMode") public abstract ReturnCode changeMode( @WebParam(name = "fileset") FileSetResource res, - @WebParam(name = "permissions") String perm); + @WebParam(name = "permissions") @XmlElement(required=true) String perm); @WebMethod(operationName = "replaceInFile") public abstract ReturnCode replaceInFile( - @WebParam(name = "file") FileResource res, - @WebParam(name = "search") String search, - @WebParam(name = "replace") String replace); + @WebParam(name = "file") @XmlElement(required=true) FileResource res, + @WebParam(name = "search") @XmlElement(required=true) String search, + @WebParam(name = "replace") @XmlElement(required=true) String replace); @WebMethod(operationName = "replaceInFile2") public abstract ReturnCode replaceInFile2( diff --git a/src/java/net/brutex/xservices/ws/impl/FileServiceImpl.java b/src/java/net/brutex/xservices/ws/impl/FileServiceImpl.java index ed16297..b3cbf39 100644 --- a/src/java/net/brutex/xservices/ws/impl/FileServiceImpl.java +++ b/src/java/net/brutex/xservices/ws/impl/FileServiceImpl.java @@ -23,6 +23,7 @@ import java.io.FileOutputStream; import java.io.IOException; import java.io.InputStream; import java.io.UnsupportedEncodingException; +import java.util.Iterator; import java.util.List; import javax.activation.DataHandler; @@ -57,6 +58,8 @@ import org.apache.tools.ant.taskdefs.optional.ReplaceRegExp; import org.apache.tools.ant.taskdefs.optional.unix.Chgrp; import org.apache.tools.ant.taskdefs.optional.unix.Chown; import org.apache.tools.ant.types.FileSet; +import org.apache.tools.ant.types.Resource; +import org.apache.tools.ant.types.ResourceCollection; /** * @@ -73,9 +76,18 @@ public class FileServiceImpl implements FileService { */ @Override @WebMethod(operationName = "basename") - public ReturnCode basename(@WebParam(name = "file") String filename, + public String basename(@WebParam(name = "file") String filename, @WebParam(name = "suffix") String suffix) { - return basename(new File(filename), suffix); + final String BASENAME_VALUE = "basename.value"; + Basename basename = new Basename(); + RunTask runner = new RunTask(basename); + basename.setFile(new File(filename)); + if (suffix != null && !suffix.equals("")) { + basename.setSuffix(suffix); + } + basename.setProperty("BASENAME_VALUE"); + ReturnCode r = runner.postTask(); + return r.getProperty("BASENAME_VALUE"); } @WebMethod(operationName = "replaceInFile") @@ -205,6 +217,21 @@ public class FileServiceImpl implements FileService { @WebParam(name = "encoding") String encoding) throws XServicesFault { return copy(src, new File(todir), plm, overwrite, encoding); } + + @Override + public ReturnCode copyFile(String fromFile, + String tofile, + boolean overwrite) throws XServicesFault { + Copy copy = new Copy(); + copy.setTaskName("Copy"); + RunTask runner = new RunTask(copy); + File f = new File(fromFile); + if( ! f.isFile() ) throw new XServicesFault("File '"+fromFile+"' not found."); + copy.setFile( new File( fromFile )); + copy.setTofile(new File(tofile)); + copy.setOverwrite(overwrite); + return runner.postTask(); + } /* * (non-Javadoc) @@ -215,12 +242,20 @@ public class FileServiceImpl implements FileService { */ @Override @WebMethod(operationName = "loadResource") - public ReturnCode loadRes(@WebParam(name = "resource") FileResource res, + public String loadRes(@WebParam(name = "resource") FileResource res, @WebParam(name = "encoding") String encoding) { if (encoding == null || encoding.equals("")) { encoding = System.getProperty("file.encoding"); } - return loadResource(res, encoding); + LoadResource lr = new LoadResource(); + lr.setTaskName("LoadResource"); + RunTask runner = new RunTask(lr); + lr.addConfigured(res.getAntResource(lr.getProject())); + lr.setEncoding(encoding); + System.out.println("Using encoding: " + encoding); + lr.setProperty("LoadResource.out"); + ReturnCode r = runner.postTask(); + return r.getProperty("LoadResource.out"); } /* @@ -232,13 +267,22 @@ public class FileServiceImpl implements FileService { */ @Override @WebMethod(operationName = "loadResourceFromArchive") - public ReturnCode loadResFromArchive( + public String loadResFromArchive( @WebParam(name = "archiveresource") ArchiveResource res, @WebParam(name = "encoding") String encoding) { if (encoding == null || encoding.equals("")) { encoding = System.getProperty("file.encoding"); } - return loadResource(res, encoding); + LoadResource lr = new LoadResource(); + lr.setTaskName("LoadResource"); + RunTask runner = new RunTask(lr); + lr.addConfigured(res.getAntResource(lr.getProject())); + lr.setEncoding(encoding); + System.out.println("Using encoding: " + encoding); + lr.setProperty("LoadResource.out"); + ReturnCode r = runner.postTask(); + return r.getProperty("LoadResource.out"); + } /* @@ -301,30 +345,6 @@ public class FileServiceImpl implements FileService { return chmod(res, perm); } - @WebMethod(exclude = true) - private ReturnCode basename(File file, String suffix) { - Basename basename = new Basename(); - RunTask runner = new RunTask(basename); - basename.setFile(file); - if (suffix != null && !suffix.equals("")) { - basename.setSuffix(suffix); - } - basename.setProperty("basename.value"); - return runner.postTask(); - } - - @WebMethod(exclude = true) - private ReturnCode loadResource(ResourceInterface src, String encoding) { - LoadResource lr = new LoadResource(); - lr.setTaskName("LoadResource"); - RunTask runner = new RunTask(lr); - lr.addConfigured(src.getAntResource(lr.getProject())); - lr.setEncoding(encoding); - System.out.println("Using encoding: " + encoding); - lr.setProperty("LoadResource.out"); - return runner.postTask(); - } - @WebMethod(exclude = true) private ReturnCode echo(String msg, File file, String encoding, boolean append) { diff --git a/test/ArchiveService-soapui-project.xml b/test/ArchiveService-soapui-project.xml new file mode 100644 index 0000000..a1d01a0 --- /dev/null +++ b/test/ArchiveService-soapui-project.xml @@ -0,0 +1,521 @@ + +http://localhost:8080/xservices/ArchiveService?WSDL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]>http://schemas.xmlsoap.org/wsdl/http://localhost:8080/xservices/ArchiveService<xml-fragment/>UTF-8http://localhost:8080/xservices/ArchiveService + + + + + c:\temp\test.rar + + c:\temp + + +]]>UTF-8http://localhost:8080/xservices/ArchiveService + + + + + + FILE + ? + + + ? + ? + + ? + ? + + +]]> \ No newline at end of file diff --git a/test/ExecuteService-soapui-project.xml b/test/ExecuteService-soapui-project.xml new file mode 100644 index 0000000..044ed47 --- /dev/null +++ b/test/ExecuteService-soapui-project.xml @@ -0,0 +1,21 @@ + + + + + + + + localhost + 23 + + brosenberger + + + + C:\Users\brosenberger> + dir c:\ + enberger> + 30000 + + + \ No newline at end of file diff --git a/test/FileServiceMTOM-soapui-project.xml b/test/FileServiceMTOM-soapui-project.xml index 5787a66..51bdfcb 100644 --- a/test/FileServiceMTOM-soapui-project.xml +++ b/test/FileServiceMTOM-soapui-project.xml @@ -1,457 +1,457 @@ -http://localhost:8080/XServices/FileServiceMTOM?wsdl - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]>http://schemas.xmlsoap.org/wsdl/http://localhost:8080/XServices/FileServiceMTOMhttp://localhost:8080/XServices/FileServiceUTF-8http://localhost:8080/XServices/FileServiceMTOM +http://localhost:8080/XServices/FileServiceMTOM?wsdl + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]>http://schemas.xmlsoap.org/wsdl/http://localhost:8080/XServices/FileServiceMTOMhttp://localhost:8080/XServices/FileService<xml-fragment/>UTF-8http://localhost:8080/XServices/FileServiceMTOM - ? + c:\temp\XServices.war - ? + .war -]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM +]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM @@ -579,20 +579,20 @@ ? -]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM +]]><xml-fragment/>UTF-8http://localhost:8080/XServices/FileServiceMTOM - ? + blubber - ? + c:\temp\something.txt - ? - ? + utf-8 + false -]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM +]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM @@ -619,27 +619,27 @@ ? -]]><xml-fragment/>UTF-8http://localhost:8080/XServices/FileServiceMTOM - - - - - - FILE - c:\temp\ - - - -]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM - - - - - - cid:166081510675 - - ? - - - +]]><xml-fragment/>UTF-8http://localhost:8080/XServices/FileService + + + + + + FILE + c:\temp\XServices.war + + + +]]>UTF-8http://localhost:8080/XServices/FileServiceMTOM + + + + + + cid:166081510675 + + ? + + + ]]> \ No newline at end of file diff --git a/test/MiscService-soapui-project.xml b/test/MiscService-soapui-project.xml new file mode 100644 index 0000000..4eca9f0 --- /dev/null +++ b/test/MiscService-soapui-project.xml @@ -0,0 +1,322 @@ + +http://localhost:8080/xservices/MiscService?WSDL + My top level documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + My binding doc + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + My portType documentation + + + + +]]>http://schemas.xmlsoap.org/wsdl/http://localhost:8080/xservices/MiscService<xml-fragment/>UTF-8http://localhost:8080/xservices/MiscService + + + + 0 + 0 + + +]]><xml-fragment/>UTF-8http://localhost:8080/xservices/MiscService + + + + 0 + 15 + + +]]><xml-fragment/>UTF-8http://localhost:8080/xservices/MiscService + + + + +]]>SEQUENTIALMiscServiceSoapBindingsleep<xml-fragment/>UTF-8http://localhost:8080/xservices/MiscService + + + + 0 + 15 + + +]]>false50250truetrue-160TIMESimple10000.5100true500 \ No newline at end of file