Subversion Repositories XServices

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
59 brianR 1
<?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">
2
	<title>Brutex XServices Documentation</title>
3
	<bookinfo>
4
		<date>February, 16th 2010</date>
5
		<author>
6
			<firstname>Brian</firstname>
7
			<surname>Rosenberger</surname>
8
			<email>bru@brutex.de</email>
9
		</author>
10
		<corpname>Brutex Network</corpname>
11
		<copyright>
12
			<year>2011</year>
13
		</copyright>
14
		<legalnotice>
15
			<para>
16
				The copyright holders make no representation about the suitability
17
				of this document for any purpose. It is provided
18
				<quote>as is</quote>
19
				without expressed or implied warranty.
20
			</para>
21
		</legalnotice>
22
		<legalnotice>
23
			<para>Apache Tomcat and Apache Ant are trademarks of the Apache
24
				Software Foundation.</para>
25
		</legalnotice>
26
		<abstract xml:base="common/abstract.xml">
27
			<title>Abstract</title>
28
			<para>In complex IT environments it is necessary to integrate
29
				different information systems with each other, exchange data
30
				between
31
				tools and automate actions and function calls depending
32
				on events
33
				arising from user interaction. To meet the requirements
34
				of
35
				integration building usually means to implement APIs and to
36
				create
37
				tool-to-tool bridges. Web Services can help to clean up
38
				bridges into
39
				interfaces as well as to abstract functions from
40
				their underlying
41
				platform and implementation.</para>
42
			<para>These are the major goals of the loosely coupled
43
				integration
44
				strategy which is in turn one essential idea of a
45
				service-oriented
46
				architecture (SOA).</para>
47
			<para>provide a low level set of functions and web services.
48
				These can
49
				be orchestrated into services and used in business
50
				processes which
51
				make up the execution part of a SOA
52
				environment.</para>
53
			<para>is an add-on to XBridgeNG 2.0. It runs standalone or in
54
				combination with XBridgeNG. Pure XBridgeNG has two
55
				components:</para>
56
			<para>
57
				<itemizedlist>
58
					<listitem>
59
						<para>XML Schema for item based data types (e.g. tickets
60
							from a bug
61
							tracker system or a database record)</para>
62
					</listitem>
63
					<listitem>
64
						<para>Set of Apache Ant tasks to function as a bridge
65
							between the
66
							XBridgeNG XML format at legacy 3rd party
67
							software (e.g. HP Quality
68
							Center, Serena TeamTrack,
69
							...)</para>
70
					</listitem>
71
					<listitem>
72
						<para>The add Web Services (SOAP) wrapper around Apache Ant
73
							tasks
74
							(since XBridgeNG 2.0)</para>
75
					</listitem>
76
				</itemizedlist>
77
			</para>
78
			<para>The current focus is on file-based operations. do not
79
				contain an
80
				integration server or a process execution
81
				engine.</para>
82
		</abstract>
83
	</bookinfo>
84
	<chapter id="installation">
85
		<beginpage/>
86
		<title>Getting started</title>
87
		<para>This chapter describes the installation.</para>
88
		<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">
89
 
90
	<section>
91
		<title>Installation</title>
92
		<para>tbd.</para>
93
		<para>Sun Java SE 1.6.0</para>
94
		<para>Apache Tomcat 7</para>
95
		<para>tbd.</para>
96
		<para>In short: Deploy .WAR file to Apache Tomcat</para>
97
		<section>
98
			<title>Securing with Basic Authentication</title>
99
			<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">
100
					http://oreilly.com/pub/a/java/archive/tomcat-tips.html?page=1</link>
101
					</para>
102
			<para>
103
 
104
			</para>
105
		</section>
106
		<section>
107
			<title>Limit access to</title>
108
			<para>Sometimes you'll only want to restrict access to to
109
				only
110
				specified host names or IP addresses. This way, only
111
				clients at
112
				those specified addresses can use the web services.
113
				Tomcat provides
114
				two configuration values for that:
115
				RemoteHostValve and
116
				RemoteAddrValve.</para>
117
			<para>These Valves allow you to filter requests by host name or
118
				by IP
119
				address, and to allow or deny hosts that match. The
120
				example below
121
				restricts access to the ArchiveService from any
122
				machine that is not
123
				the local host.</para>
124
			<programlisting language="xml">&lt;Context
125
				path="/XService/ArchiveService"
126
				...&gt; &lt;Valve
127
				className="org.apache.catalina.valves.RemoteAddrValve"
128
				allow="127.0.0.1" deny=""/&gt; &lt;/Context&gt;
129
			</programlisting>
130
			<para>If no allow pattern is given, then patterns that match
131
				the deny
132
				attribute patterns will be rejected, and all others
133
				will be allowed.
134
				Similarly, if no deny pattern is given,
135
				patterns that match the
136
				allow attribute will be allowed, and
137
				all others will be denied.
138
				</para>
139
			<para>The &lt;context&gt; element must be placed into the
140
				server.xml
141
				file (into &lt;engine&gt;&lt;host&gt;).</para>
142
		</section>
143
	</section>
144
</section>
145
	</chapter>
146
	<chapter id="services">
147
		<beginpage/>
148
		<title>Available Services</title>
149
		<para>List of available web services and their operations.</para>
150
		<section id="archiveservices" version="5.0" xml:base="ArchiveServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
151
			<title>ArchiveServices</title>
152
			<para>The ArchiveService bundles file packing operations. Its
153
				WSDL is
154
				located at
155
				http://server:port/XServices/ArchiveService?wsdl</para>
156
		</section>
67 brianR 157
		<section id="dateservices" version="5.0" xml:base="DateServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
158
	<title>DateServices</title>
159
	<para>The DateService bundles various date and time related operations. Its WSDL is located at
160
		http://server:port/XServices/DateService?wsdl</para>
161
 
162
</section>
59 brianR 163
		<section id="executeservices" version="5.0" xml:base="ExecuteServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
164
	<title>ExecuteServices</title>
165
	<para>The ExecuteService bundles local and remote command
166
		execution operations. Its WSDL is located at
167
		http://server:port/XServices/ExecuteService?wsdl</para>
168
		<section version="5.0" xml:base="ExecuteServices/rExec.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
169
	<title>rExec
170
	</title>
171
	<para>provides remote execution facilities with authentication based on
172
		user names and passwords.</para>
173
	<section>
174
		<title>Input parameters
175
		</title>
176
		<para/>
177
		<table frame="all">
178
			<title>rExec
179
				input parameters
180
			</title>
181
			<tgroup cols="4">
182
				<colspec colname="parameter" colnum="1"/>
183
				<colspec colname="type" colnum="2"/>
184
				<colspec colname="required" colnum="3"/>
185
				<colspec colname="description" colnum="4"/>
186
				<thead>
187
					<row>
188
						<entry>parameter</entry>
189
						<entry>type</entry>
190
						<entry>required</entry>
191
						<entry>description</entry>
192
					</row>
193
				</thead>
194
				<tbody>
195
					<row>
196
						<entry>host</entry>
197
						<entry>HostConnection</entry>
198
						<entry>Yes</entry>
199
						<entry>
200
							Host where to execute the command. See
201
							<link linkend="hostconnection">HostConnection</link>
202
							.
203
						</entry>
204
					</row>
205
					<row>
206
						<entry>command</entry>
207
						<entry>String</entry>
208
						<entry>No</entry>
209
						<entry>Any command including arguments</entry>
210
					</row>
211
          <row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
212
            <entry>timeout</entry>
213
            <entry>Long</entry>
214
            <entry>Yes</entry>
215
            <entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
216
          </row>
217
				</tbody>
218
			</tgroup>
219
		</table>
220
		<para/>
221
	</section>
222
	<section>
223
		<title>Output parameters
224
		</title>
225
		<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
226
	<title>ReturnCode type</title>
227
	<para>
228
		The ReturnCode type is used as the generic answer type for most of the
229
		<application class="software">BruteXservices</application>
230
		operations.
231
	</para>
232
	<para>
233
		The defining Java class is
234
		<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
235
			<classname>net.brutex.xservices.types.ReturnCode</classname>
236
		</ulink>
237
		.
238
	</para>
239
	<bridgehead renderas="sect3">Schema definition</bridgehead>
240
	<programlisting language="xml"><![CDATA[
241
<xs:complexType name="ReturnCodeType">
242
    <xs:sequence>
243
        <xs:element name="returnCode" type="xs:int"/>
244
        <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
245
        <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
246
        <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
247
    </xs:sequence>
248
</xs:complexType>]]>
249
	</programlisting>
250
 
251
	<bridgehead renderas="sect3">Example XML</bridgehead>
252
	<programlisting language="xml">
253
		&lt;ReturnCode
254
		xmlns:ns2="http://ws.xservices.brutex.net"&gt;
255
		&lt;returnCode&gt;0&lt;/returnCode&gt;
256
		&lt;stdOut/&gt;
257
		&lt;stdErr/&gt;
258
		&lt;propertyList&gt;
259
		<lineannotation>
260
			See
261
			<link linkend="antproperty">tns:antProperty</link>
262
			for details about the &lt;propertyList&gt; elements.
263
		</lineannotation>
264
		&lt;name&gt;key1&lt;/name&gt;
265
		&lt;value&gt;value1&lt;/value&gt;
266
		&lt;/propertyList&gt;
267
		&lt;propertyList&gt;
268
		&lt;name&gt;key2&lt;/name&gt;
269
		&lt;value&gt;value2&lt;/value&gt;
270
		&lt;/propertyList&gt;
271
		&lt;/ReturnCode&gt;
272
	</programlisting>
273
 
274
</section>
275
	</section>
276
</section>
277
		<section version="5.0" xml:base="ExecuteServices/runCommand.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
278
	<title>runCommand</title>
279
	<para>Run an executable with arguments on the server providing the web
280
		service. The command is run within the environment and under the user
281
		privileges of the user who is running the Tomcat Server.</para>
282
	<section>
283
		<title>Input parameters
284
		</title>
285
		<para/>
286
		<table frame="all">
287
			<title>runCommand input parameters</title>
288
			<tgroup cols="4">
289
				<colspec colname="parameter" colnum="1"/>
290
				<colspec colname="type" colnum="2"/>
291
				<colspec colname="required" colnum="3"/>
292
				<colspec colname="description" colnum="4"/>
293
				<thead>
294
					<row>
295
						<entry>parameter</entry>
296
						<entry>type</entry>
297
						<entry>required</entry>
298
						<entry>description</entry>
299
					</row>
300
				</thead>
301
				<tbody>
302
					<row>
303
						<entry>executable</entry>
304
						<entry>String</entry>
305
						<entry>Yes</entry>
306
						<entry>Command to be run. The command may be specified with full
307
							path using forward slash "/" as path separator.</entry>
308
					</row>
309
					<row>
310
						<entry>argline</entry>
311
						<entry>String</entry>
312
						<entry>No</entry>
313
						<entry>Any command line arguments</entry>
314
					</row>
315
          <row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
316
            <entry>timeout</entry>
317
            <entry>Long</entry>
318
            <entry>Yes</entry>
319
            <entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
320
          </row>
321
				</tbody>
322
			</tgroup>
323
		</table>
324
		<para/>
325
	</section>
326
	<section>
327
		<title>Output parameters
328
		</title>
329
		<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
330
	<title>ReturnCode type</title>
331
	<para>
332
		The ReturnCode type is used as the generic answer type for most of the
333
		<application class="software">BruteXservices</application>
334
		operations.
335
	</para>
336
	<para>
337
		The defining Java class is
338
		<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
339
			<classname>net.brutex.xservices.types.ReturnCode</classname>
340
		</ulink>
341
		.
342
	</para>
343
	<bridgehead renderas="sect3">Schema definition</bridgehead>
344
	<programlisting language="xml"><![CDATA[
345
<xs:complexType name="ReturnCodeType">
346
    <xs:sequence>
347
        <xs:element name="returnCode" type="xs:int"/>
348
        <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
349
        <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
350
        <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
351
    </xs:sequence>
352
</xs:complexType>]]>
353
	</programlisting>
354
 
355
	<bridgehead renderas="sect3">Example XML</bridgehead>
356
	<programlisting language="xml">
357
		&lt;ReturnCode
358
		xmlns:ns2="http://ws.xservices.brutex.net"&gt;
359
		&lt;returnCode&gt;0&lt;/returnCode&gt;
360
		&lt;stdOut/&gt;
361
		&lt;stdErr/&gt;
362
		&lt;propertyList&gt;
363
		<lineannotation>
364
			See
365
			<link linkend="antproperty">tns:antProperty</link>
366
			for details about the &lt;propertyList&gt; elements.
367
		</lineannotation>
368
		&lt;name&gt;key1&lt;/name&gt;
369
		&lt;value&gt;value1&lt;/value&gt;
370
		&lt;/propertyList&gt;
371
		&lt;propertyList&gt;
372
		&lt;name&gt;key2&lt;/name&gt;
373
		&lt;value&gt;value2&lt;/value&gt;
374
		&lt;/propertyList&gt;
375
		&lt;/ReturnCode&gt;
376
	</programlisting>
377
 
378
</section>
379
	</section>
380
</section>
381
		<section version="5.0" xml:base="ExecuteServices/runCommandWithSSH.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
382
	<title>runCommandWithSSH</title>
383
	<para>Executes a command through a SSH session.</para>
384
	<section>
385
		<title>Input parameters
386
		</title>
387
		<para/>
388
		<table frame="all">
389
			<title>runCommandWithSSH input parameters</title>
390
			<tgroup cols="4">
391
				<colspec colname="parameter" colnum="1"/>
392
				<colspec colname="type" colnum="2"/>
393
				<colspec colname="required" colnum="3"/>
394
				<colspec colname="description" colnum="4"/>
395
				<thead>
396
					<row>
397
						<entry>parameter</entry>
398
						<entry>type</entry>
399
						<entry>required</entry>
400
						<entry>description</entry>
401
					</row>
402
				</thead>
403
				<tbody>
404
					<row>
405
						<entry>host</entry>
406
						<entry>HostConnection</entry>
407
						<entry>Yes</entry>
408
						<entry>
409
							Host to connect to (see:
410
							<link linkend="hostconnection">tns:HostConnection</link>
411
							)
412
						</entry>
413
					</row>
414
					<row>
415
						<entry>command</entry>
416
						<entry>String</entry>
417
						<entry>No</entry>
418
						<entry>The command to execute.</entry>
419
					</row>
420
          <row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
421
            <entry>timeout</entry>
422
            <entry>Long</entry>
423
            <entry>Yes</entry>
424
            <entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
425
          </row>
426
				</tbody>
427
			</tgroup>
428
		</table>
429
		<para/>
430
	</section>
431
	<section>
432
		<title>Output parameters
433
		</title>
434
		<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
435
	<title>ReturnCode type</title>
436
	<para>
437
		The ReturnCode type is used as the generic answer type for most of the
438
		<application class="software">BruteXservices</application>
439
		operations.
440
	</para>
441
	<para>
442
		The defining Java class is
443
		<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
444
			<classname>net.brutex.xservices.types.ReturnCode</classname>
445
		</ulink>
446
		.
447
	</para>
448
	<bridgehead renderas="sect3">Schema definition</bridgehead>
449
	<programlisting language="xml"><![CDATA[
450
<xs:complexType name="ReturnCodeType">
451
    <xs:sequence>
452
        <xs:element name="returnCode" type="xs:int"/>
453
        <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
454
        <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
455
        <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
456
    </xs:sequence>
457
</xs:complexType>]]>
458
	</programlisting>
459
 
460
	<bridgehead renderas="sect3">Example XML</bridgehead>
461
	<programlisting language="xml">
462
		&lt;ReturnCode
463
		xmlns:ns2="http://ws.xservices.brutex.net"&gt;
464
		&lt;returnCode&gt;0&lt;/returnCode&gt;
465
		&lt;stdOut/&gt;
466
		&lt;stdErr/&gt;
467
		&lt;propertyList&gt;
468
		<lineannotation>
469
			See
470
			<link linkend="antproperty">tns:antProperty</link>
471
			for details about the &lt;propertyList&gt; elements.
472
		</lineannotation>
473
		&lt;name&gt;key1&lt;/name&gt;
474
		&lt;value&gt;value1&lt;/value&gt;
475
		&lt;/propertyList&gt;
476
		&lt;propertyList&gt;
477
		&lt;name&gt;key2&lt;/name&gt;
478
		&lt;value&gt;value2&lt;/value&gt;
479
		&lt;/propertyList&gt;
480
		&lt;/ReturnCode&gt;
481
	</programlisting>
482
 
483
</section>
484
	</section>
485
	<section>
486
		<title>Sample Request:</title>
487
		<programlisting language="xml">
488
	<![CDATA[
489
      <ws:runCommandWithSSH>
490
         <host>
491
            <hostname>ssh.brutex.net</hostname>
492
            <port>22</port>
493
            <user>roger</user>
494
            <password>xxx</password>
495
         </host>
496
         <command>ls /etc/</command>
497
         <timeout>30000</timeout>
498
      </ws:runCommandWithSSH>
499
	]]></programlisting>
500
	</section>
501
</section>
502
		<section version="5.0" xml:base="ExecuteServices/telnet.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
503
	<title>telnet</title>
504
	<para>Runs a telnet session with an "expect shell" like behaviour.</para>
505
	<section>
506
		<title>Input parameters
507
		</title>
508
		<para/>
509
		<table frame="all">
510
			<title>telnet input parameters</title>
511
			<tgroup cols="4">
512
				<colspec colname="parameter" colnum="1"/>
513
				<colspec colname="type" colnum="2"/>
514
				<colspec colname="required" colnum="3"/>
515
				<colspec colname="description" colnum="4"/>
516
				<thead>
517
					<row>
518
						<entry>parameter</entry>
519
						<entry>type</entry>
520
						<entry>required</entry>
521
						<entry>description</entry>
522
					</row>
523
				</thead>
524
				<tbody>
525
					<row>
526
						<entry>host</entry>
527
						<entry>HostConnection</entry>
528
						<entry>Yes</entry>
529
						<entry>Host to connect to (see: <link linkend="hostconnection">tns:HostConnection</link>)</entry>
530
					</row>
531
					<row>
532
						<entry>prompt</entry>
533
						<entry>String</entry>
534
						<entry>No</entry>
535
						<entry>The prompt string to expect after login. This is used to recognize when
536
						 the session is open.</entry>
537
					</row>
538
					<row>
539
						<entry>command</entry>
540
						<entry>String</entry>
541
						<entry>No</entry>
542
						<entry>The command to execute.</entry>
543
					</row>
544
					<row>
545
						<entry>expect</entry>
546
						<entry>String</entry>
547
						<entry>No</entry>
548
						<entry>The prompt to expect after the command has been executed successfully.</entry>
549
					</row>
550
          <row xml:base="file:/C:/Users/brosenberger/workspace/XServices/doc/entities.ent">
551
            <entry>timeout</entry>
552
            <entry>Long</entry>
553
            <entry>Yes</entry>
554
            <entry>Timeout in milliseconds. The command is forcefully terminated when timeout is reached.</entry>
555
          </row>
556
				</tbody>
557
			</tgroup>
558
		</table>
559
		<para/>
560
	</section>
561
	<section>
562
		<title>Output parameters</title>
563
		<section version="5.0" xml:base="ExecuteServices/../types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
564
	<title>ReturnCode type</title>
565
	<para>
566
		The ReturnCode type is used as the generic answer type for most of the
567
		<application class="software">BruteXservices</application>
568
		operations.
569
	</para>
570
	<para>
571
		The defining Java class is
572
		<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
573
			<classname>net.brutex.xservices.types.ReturnCode</classname>
574
		</ulink>
575
		.
576
	</para>
577
	<bridgehead renderas="sect3">Schema definition</bridgehead>
578
	<programlisting language="xml"><![CDATA[
579
<xs:complexType name="ReturnCodeType">
580
    <xs:sequence>
581
        <xs:element name="returnCode" type="xs:int"/>
582
        <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
583
        <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
584
        <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
585
    </xs:sequence>
586
</xs:complexType>]]>
587
	</programlisting>
588
 
589
	<bridgehead renderas="sect3">Example XML</bridgehead>
590
	<programlisting language="xml">
591
		&lt;ReturnCode
592
		xmlns:ns2="http://ws.xservices.brutex.net"&gt;
593
		&lt;returnCode&gt;0&lt;/returnCode&gt;
594
		&lt;stdOut/&gt;
595
		&lt;stdErr/&gt;
596
		&lt;propertyList&gt;
597
		<lineannotation>
598
			See
599
			<link linkend="antproperty">tns:antProperty</link>
600
			for details about the &lt;propertyList&gt; elements.
601
		</lineannotation>
602
		&lt;name&gt;key1&lt;/name&gt;
603
		&lt;value&gt;value1&lt;/value&gt;
604
		&lt;/propertyList&gt;
605
		&lt;propertyList&gt;
606
		&lt;name&gt;key2&lt;/name&gt;
607
		&lt;value&gt;value2&lt;/value&gt;
608
		&lt;/propertyList&gt;
609
		&lt;/ReturnCode&gt;
610
	</programlisting>
611
 
612
</section>
613
	</section>
614
	<section>
615
	<title>Sample Request:</title>
616
	<programlisting language="xml">
617
	<![CDATA[
618
	 <ws:telnet>
619
         <host>
620
            <hostname>localhost</hostname>
621
            <port>23</port>
622
            <user>brosenberger</user>
623
            <password></password>
624
         </host>
625
         <prompt>C:\Users\brosenberger&gt;</prompt>
626
         <command>dir c:\temp</command>
627
         <expect>enberger&gt;</expect>
628
         <timeout>60000</timeout>
629
      </ws:telnet>
630
	]]></programlisting>
631
	</section>
632
</section>
633
</section>
634
		<section id="fileservices" version="5.0" xml:base="FileServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
635
	<title>FileServices</title>
636
	<para>The FileServces bundles various file operations. Its WSDL is located at
637
		http://server:port/XServices/FileService?wsdl</para>
638
</section>
639
		<section id="miscservices" version="5.0" xml:base="MiscServices.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
640
	<title>MiscServices</title>
641
	<para>The MiscService bundles various operations. Its WSDL is located at
642
		http://server:port/XServices/MiscService?wsdl</para>
77 brianR 643
		<section version="5.0" xml:base="MiscServices/generateUUID.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
644
	<title>generateUUID</title>
645
	<para>Generates a UUID that represents a 128-bit value. This operation does not require any
646
	 input parameters. The output has the format:
647
	<screen>
648
		0xFFFFFFFF00000000 time_low
649
		0x00000000FFFF0000 time_mid
650
		0x000000000000F000 version
651
		0x0000000000000FFF time_hi
652
	</screen>
653
 
654
		The least significant long consists of the following unsigned fields:
655
	<screen>
656
		0xC000000000000000 variant
657
		0x3FFF000000000000 clock_seq
658
		0x0000FFFFFFFFFFFF node
659
	</screen>
660
	Sample response:
661
	<screen><![CDATA[
662
<soap:Envelope
663
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
664
   <soap:Body>
665
      <ns1:generateUUIDResponse
666
      	xmlns:ns1="http://ws.xservices.brutex.net">
667
         <ns1:return>]]><emphasis>33b9e5c8-9102-423b-88af-bbee479ebea8</emphasis><![CDATA[</ns1:return>
668
      </ns1:generateUUIDResponse>
669
   </soap:Body>
670
</soap:Envelope>
671
]]></screen>
672
</para>
673
</section>
674
		<section version="5.0" xml:base="MiscServices/getHostinfo.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
675
	<title>getHostinfo</title>
676
	<para>Collect information about a host address.
677
	Sample request:
678
<screen><![CDATA[
679
<soapenv:Envelope
680
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
681
	xmlns:ws="http://ws.xservices.brutex.net">
682
  		<soapenv:Header/>
683
  		<soapenv:Body>
684
		<ws:getHostinfo>
685
        		<ws:hostname>]]><emphasis>google.com</emphasis><![CDATA[</ws:hostname>
686
     		</ws:getHostinfo>
687
  		</soapenv:Body>
688
</soapenv:Envelope>
689
]]></screen>
690
	Sample response:
691
	<screen><![CDATA[
692
<soap:Envelope
693
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
694
  	<soap:Body>
695
      <ns1:getHostinfoResponse
696
      	xmlns:ns1="http://ws.xservices.brutex.net">
697
         <ns1:return>
698
            <ns1:domain>]]><emphasis>1e100.net</emphasis><![CDATA[</ns1:domain>
699
            <ns1:ip4>]]><emphasis>173.194.66.105</emphasis><![CDATA[</ns1:ip4>
700
            <ns1:ip6>]]><emphasis>::</emphasis><![CDATA[</ns1:ip6>
701
            <ns1:name>]]><emphasis>we-in-f105</emphasis><![CDATA[</ns1:name>
702
         </ns1:return>
703
      </ns1:getHostinfoResponse>
704
   	</soap:Body>
705
</soap:Envelope>
706
]]></screen>
707
</para>
708
</section>
59 brianR 709
</section>
710
	</chapter>
711
 
712
	<chapter id="xmltypes">
713
		<beginpage/>
714
		<title>XML Types</title>
715
		<para>This chapter bundles the documentation for common XML types used
716
			by XServices web service.</para>
717
		<section version="5.0" xml:base="Types.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
718
	<!-- Sort alphabetically -->
719
	<section xml:base="types/AntProperty.xml">
720
<title>AntProperty type</title>
721
			<para>The AntProperty type defines a list of key/value pairs.</para>
722
			<para>
723
				The defining Java class is
724
				<ulink url="javadoc/net/brutex/xservices/types/AntProperty.html">
725
					<classname>net.brutex.xservices.types.AntProperty</classname>
726
				</ulink>
727
				.
728
			</para>
729
 
730
			<programlisting language="xml"><![CDATA[
731
<xs:complexType name="antProperty">
732
   <xs:sequence>
733
      <xs:element name="name" type="xs:string"/>
734
      <xs:element name="value" type="xs:string"/>
735
   </xs:sequence>
736
</xs:complexType>]]>
737
			</programlisting>
738
 
739
			<programlisting language="xml"><![CDATA[
740
<AntProperty>
741
    <name>key2</name>
742
    <value>value2</value>
743
</AntProperty>]]>
744
			</programlisting>
745
		</section>
746
	<section xml:base="types/FileResource.xml">
747
<title>FileResource type</title>
748
			<para>The FileResource type defines an URI to a file with optional on-the-fly decompression.</para>
749
			<para>
750
				The defining Java class is
751
				<ulink url="javadoc/net/brutex/xservices/types/FileResource.html">
752
					<classname>net.brutex.xservices.types.FileResource</classname>
753
				</ulink>
754
				.
755
			</para>
756
 
757
			<programlisting language="xml"><![CDATA[
758
<xs:complexType name="FileResourceType">
759
	<xs:sequence>
760
    	<xs:element default="FILE" name="type" type="tns:type"/>
761
        <xs:element name="uri" type="xs:string"/>
762
   </xs:sequence>
763
</xs:complexType>]]>
764
			</programlisting>
765
			<para>Available types:</para>
766
			<para>FILE: URI points to a local file resource. Examples: c:\temp\something.txt, c:/dir/another.file, /home/brian/file</para>
767
			<para>URL: File from URL (http, https, ftp, ...). Example: http://brutex.net/file.pdf</para>
768
			<para>GZIP and BZIP2: File from a local file system with on-the-fly decompression.</para>
769
			<programlisting language="xml"><![CDATA[
770
<resource>
771
	<type>FILE</type>
772
    <uri>c:\temp\xservices.war</uri>
773
</resource>]]>
774
			</programlisting>
775
		</section>
776
	<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">
777
	<title>HostConnection type</title>
778
	<para>The HostConnection type identifies a server resource and login
779
		credentials.</para>
780
	<para>
781
		The defining Java class is
782
		<ulink url="javadoc/net/brutex/xservices/types/HostConnection.html">
783
			<classname>net.brutex.xservices.types.HostConnection</classname>
784
		</ulink>
785
		.
786
	</para>
787
	<bridgehead renderas="sect3">Schema definition</bridgehead>
788
	<programlisting language="xml"><![CDATA[
789
<xs:complexType name="connection">
790
   <xs:sequence>
791
      <xs:element name="hostname" type="xs:string"/>
792
      <xs:element name="port" type="xs:int"/>
793
      <xs:element minOccurs="0" name="user" type="xs:string"/>
794
      <xs:element minOccurs="0" name="password" type="xs:string"/>
795
   </xs:sequence>
796
</xs:complexType>
797
]]>
798
	</programlisting>
799
	<bridgehead renderas="sect3">Example XML</bridgehead>
800
	<programlisting language="xml"><![CDATA[
801
<host>
802
   <hostname>server.brutex.net</hostname>
803
   <port>512</port> <!-- default rExec port -->
804
   <user>brian</user>
805
   <!--Optional:-->
806
   <password>somepass</password>
807
</host>
808
]]>
809
	</programlisting>
810
</section>
811
	<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">
812
	<title>PatternElement type</title>
813
	<para>The PatternElement type defines single string pattern for file/
814
		directory matching.</para>
815
	<para>
816
		The defining Java class is
817
		<ulink url="javadoc/net/brutex/xservices/types/PatternElement.html">
818
			<classname>net.brutex.xservices.types.PatternElement</classname>
819
		</ulink>
820
		.
821
	</para>
822
	<para>
823
		These patterns look exactly like those used in Apache Ant
824
		<ulink url="http://ant.apache.org/manual/dirtasks.html#patterns">Patterns</ulink>.
825
		The '*' matches zero or more characters and the
826
		'?' will match a single character.
827
		Both symbols can be combined in one pattern. The '**'
828
		symbol can be used to match any directory deepth.
829
	</para>
830
	<para>Some example patterns:</para>
831
	<para>
832
		<parameter>**/mydir/**</parameter>
833
	</para>
834
	<para>Match all file that are located in any directory that has
835
		"mydir" string in its pathname. Also applies to files with
836
		"mydir" in their name.</para>
837
	<para>
838
		<parameter>/mydir/</parameter>
839
	</para>
840
	<para>The
841
		parser will automatically append an '**' symbol, thus the
842
		resulting pattern is
843
		<parameter>/mydir/**</parameter>.
844
		All files below the "/mydir/" directory (including its
845
		sub-directories will be chosen.
846
	</para>
847
	<note>
848
		<para>The pattern is OS independent. You should always use
849
			"/" as path separator, even on windows based systems.
850
		</para>
851
	</note>
852
	<bridgehead renderas="sect3">Schema definition</bridgehead>
853
	<programlisting language="xml"><![CDATA[<xs:simpleType name="patternElement">
854
    <xs:restriction base="xs:string"/>
855
</xs:simpleType>]]></programlisting>
856
 
857
	<bridgehead renderas="sect3">Example XML</bridgehead>
858
	<programlisting language="xml"><![CDATA[<PatternElement>**/*</PatternElement>]]></programlisting>
859
 
860
</section>
861
	<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">
862
	<title>PatternSetType type</title>
863
	<para>The PatternSetType exposes various filters/ selectors for the
864
		selection of resources (files).</para>
865
	<para>
866
		The defining Java class is
867
		<ulink url="javadoc/net/brutex/xservices/types/PatternSetType.html">
868
			<classname>net.brutex.xservices.types.PatternSetType</classname>
869
		</ulink>
870
		.
871
	</para>
872
	<bridgehead renderas="sect3">Schema definition</bridgehead>
873
	<programlisting language="xml"><![CDATA[
874
<xs:complexType name="patternSetType">
875
    <xs:sequence>
876
        <xs:element default="**/*" maxOccurs="unbounded" minOccurs="0" name="include" type="]]><link linkend="patternelement">tns:patternElement</link><![CDATA["/>
877
        <xs:element maxOccurs="unbounded" minOccurs="0" name="exclude" type="]]><link linkend="patternelement">tns:patternElement</link><![CDATA["/>
878
        <xs:element minOccurs="0" name="selector" nillable="true" type="]]><link linkend="selectortype">tns:selectorType</link><![CDATA["/>
879
    </xs:sequence>
880
</xs:complexType>]]>
881
	</programlisting>
882
	<bridgehead renderas="sect3">Example XML</bridgehead>
883
	<programlisting language="xml"><![CDATA[
884
            tbd.]]>
885
	</programlisting>
886
</section>
887
	<section version="5.0" xml:base="types/ReturnCode.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
888
	<title>ReturnCode type</title>
889
	<para>
890
		The ReturnCode type is used as the generic answer type for most of the
891
		<application class="software">BruteXservices</application>
892
		operations.
893
	</para>
894
	<para>
895
		The defining Java class is
896
		<ulink url="javadoc/net/brutex/xservices/types/ReturnCode.html">
897
			<classname>net.brutex.xservices.types.ReturnCode</classname>
898
		</ulink>
899
		.
900
	</para>
901
	<bridgehead renderas="sect3">Schema definition</bridgehead>
902
	<programlisting language="xml"><![CDATA[
903
<xs:complexType name="ReturnCodeType">
904
    <xs:sequence>
905
        <xs:element name="returnCode" type="xs:int"/>
906
        <xs:element minOccurs="0" name="stdOut" type="xs:string"/>
907
        <xs:element minOccurs="0" name="stdErr" type="xs:string"/>
908
        <xs:element maxOccurs="unbounded" minOccurs="0" name="propertyList" nillable="true" type="]]><link linkend="antproperty">tns:antProperty</link><![CDATA["/>
909
    </xs:sequence>
910
</xs:complexType>]]>
911
	</programlisting>
912
 
913
	<bridgehead renderas="sect3">Example XML</bridgehead>
914
	<programlisting language="xml">
915
		&lt;ReturnCode
916
		xmlns:ns2="http://ws.xservices.brutex.net"&gt;
917
		&lt;returnCode&gt;0&lt;/returnCode&gt;
918
		&lt;stdOut/&gt;
919
		&lt;stdErr/&gt;
920
		&lt;propertyList&gt;
921
		<lineannotation>
922
			See
923
			<link linkend="antproperty">tns:antProperty</link>
924
			for details about the &lt;propertyList&gt; elements.
925
		</lineannotation>
926
		&lt;name&gt;key1&lt;/name&gt;
927
		&lt;value&gt;value1&lt;/value&gt;
928
		&lt;/propertyList&gt;
929
		&lt;propertyList&gt;
930
		&lt;name&gt;key2&lt;/name&gt;
931
		&lt;value&gt;value2&lt;/value&gt;
932
		&lt;/propertyList&gt;
933
		&lt;/ReturnCode&gt;
934
	</programlisting>
935
 
936
</section>
937
	<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">
938
    <title>SelectorType type</title>
939
    <para>The SelectorType exposes various selectors for the selection of resources (files).</para>
940
    <para>The defining Java class is
941
        <ulink url="javadoc/net/brutex/xservices/types/SelectorType.html">
942
    <classname>net.brutex.xservices.types.SelectorType</classname></ulink>.</para>
943
<bridgehead renderas="sect3">Schema definition</bridgehead>
944
        <programlisting language="xml"><![CDATA[
945
         <xs:complexType abstract="true" name="selectorType">
946
            <xs:sequence>
947
               <xs:element maxOccurs="unbounded" minOccurs="0" name="contains" nillable="true" type="tns:containsSelectorType"/>
948
            </xs:sequence>
949
         </xs:complexType>]]>
950
</programlisting>
951
<bridgehead renderas="sect3">Example XML</bridgehead>
952
    <programlisting language="xml"><![CDATA[
953
            tbd.]]>
954
        </programlisting>
955
</section>
956
</section>
957
	</chapter>
958
</book>