1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<HTML lang=en dir=ltr xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<HEAD>
<TITLE>Creating a Tcl Web Service</TITLE>
<META http-equiv=Content-Type content="text/html; charset=utf-8">
<META content="Creating a Tcl Web Service" name=KEYWORDS>
<link rel="stylesheet" href="style.css" type="text/css" media="screen">
</HEAD>
<BODY>
<H1>Creating a Tcl Web Service</H1>
<TABLE class=toc id=toc>
<TBODY>
<TR>
<TD>
<DIV id=toctitle>
<H2>Contents</H2></DIV>
<UL>
<LI class=toclevel-1><A href="#Loading_the_Webservices_Server_Package"><SPAN
class=tocnumber>1</SPAN> <SPAN class=toctext>Loading the Webservices
Server Package</SPAN></A>
<LI class=toclevel-1><A href="#Defining_a_Service"><SPAN
class=tocnumber>2</SPAN> <SPAN class=toctext>Defining a
Service</SPAN></A>
<LI class=toclevel-1><A href="#Defining_an_Operation_.28aka_a_Service_Procedure.29"><SPAN
class=tocnumber>3</SPAN> <SPAN class=toctext>Defining an Operation (aka
a Service Procedure)</SPAN></A>
<LI class=toclevel-1><A href="#Declaring_Complex_Types"><SPAN
class=tocnumber>4</SPAN> <SPAN class=toctext>Declaring Complex
Types</SPAN></A> </LI>
</UL>
</TD>
</TR>
</TBODY>
</TABLE>
<A name=Loading_the_Webservices_Server_Package></A>
<H2>Loading the Webservices Server Package </H2>
<p>To load the webservices server package, do: </p>
<PRE> package require WS::Server</PRE>
<p>This command will only load the server the first time it is used, so it
causes no ill effects to put this in each file declaring a service or service
procedure. </p>
<h3>Using as part of TclHttpd</h3>
<p>
The Web Services package, WS::Server, is not a standalone application, but rather is designed
to be a "module" of TclHttpd.
The following command is normally placed in httpdthread.tcl:
</p>
<h3>Embedding in a Standalone Application</h3>
<p>
To embed a Web Service into an application, the application needs to be event
driven and you also need to use the <b>WS::Embeded</b> package. You also must
define the service with the <i>-mode=embedded</i> option.
</p>
<p>
See also
<a href="Embedded_Web_Service.html">Embedding a Web Service into an application</A>.
</p>
<h3>Using with Apache Rivet</h3>
<p>
<a href="http://tcl.apache.org/rivet/">Apache Rivet</a> is a module (mod_rivet) that can be loaded by Apache httpd server to
allow web pages to run embedded Tcl commands in a way similar to PHP. To create
a Web Service in Rivet, use the example EchoRivetService.rvt as a starting point
by simply copying it into any directory served by your Apache instance. You should be able to
immediately access that new location at the following URLs:
</p>
<PRE> /path/to/EchoRivetService.rvt/doc
Displays an HTML page describing the service
/path/to/EchoRivetService.rvt/wsdl
Returns a WSDL describing the service
/path/to/EchoRivetService.rvt/op
Invoke an operation
</PRE>
<p>
If you would prefer to expose the published URLs of your service differently, you can use the
standard Apache mod_rewrite or mod_alias modules to transparently map any other URL to those locations.
</p>
<HR>
<A name=Defining_a_Service></A>
<H2>Defining a Service </H2>
<p>
The code that defines a service is normally placed in one or more files in the custom directory.
</p>
<p><b>Procedure Name : <i>::WS::Server::Service</i></b> </p>
<p><b>Description</b> : Declare a Web Service, the following URLs will
exist </p><PRE> /service/<ServiceName>
Displays an HTML page describing the service
/service/<ServiceName>/wsdl
Returns a WSDL describing the service
/service/<ServiceName>/op
Invoke an operation
</PRE>
<p><b>Arguments</b> : this procedure uses position independent arguments,
they are: </p><pre>
-hostcompatibility32 bool - Activate version 3.2.0 compatibility
mode for -host parameter.
Defaults to true.
-host - The host specification within XML namespaces
of the transmitted XML files.
This should be unique.
Defaults to localhost.
If 3.2 compatibility is activated, the default
value is changed to ip:port in embedded mode.
-hostlocation - The host name, which is promoted within the
generated WSDL file. Defaults to localhost.
If 3.2 compatibility is activated, the
default value is equal to the -host parameter.
-hostlocationserver bool - If true, the host location is set by
the current server settings.
In case of httpd server, this value is imported.
For other servers or if this fails, the value
is the current ip:port.
The default value is true.
In case of 3.2 compatibility, the default
value is true for tclhttpd, false otherwise.
-hostProtocol - Define the host protocol (http, https) for the
WSDL location URL. The special value "server"
(default) follows the TCP/IP server specification.
This is implemented for Embedded server and tclhttpd.
Remark that the protocol for XML namespaces
is always "http".
-description - The HTML description for this service
-htmlhead - The title string of the service description
-author - The author property in the service description
-xmlnamespace - Extra XML namespaces used by the service
-service - The service name (this will also be used for
the Tcl namespace of the procedures that implement
the operations.
-premonitor - This is a command prefix to be called before
an operation is called. The following arguments are
added to the command prefix:
PRE serviceName operationName operArgList
-postmonitor - This is a command prefix to be called after
an operation is called. The following arguments are
added to the command prefix:
POST serviceName operationName OK|ERROR results
-inheaders - List of input header types.
-outheaders - List of output header types.
-intransform - Inbound (request) transform procedure (2.0.3 and later).
The signature of the command must be:
cmd \
mode (REQUEST) \
xml \
notUsed_1 \
notUsed_2
-outtransform - Outbound (reply) transform procedure (2.0.3 and later).
The signature of the command must be:
cmd \
mode (REPLY) \
xml \
operation \
resultDict
-checkheader - Command prefix to check headers.
If the call is not to be allowed, this command
should raise an error.
The signature of the command must be:
cmd \
service \
operation \
caller_ipaddr \
http_header_list \
soap_header_list
-mode - Mode that service is running in. Must be one of:
tclhttpd -- running inside of tclhttpd or an
environment that supplies a
compatible Url_PrefixInstall
and Httpd_ReturnData commands
embedded -- using the ::WS::Embedded package
aolserver -- using the ::WS::AolServer package
wub -- using the ::WS::Wub package
wibble -- running inside wibble
rivet -- running inside Apache Rivet (mod_rivet)
-ports - List of ports for embedded mode. Default: 80
NOTE -- a call should be to
::WS::Embedded::Listen for each port
in this list prior to calling ::WS::Embeded::Start
-prefix - Path prefix used for the namespace and endpoint
Defaults to "/service/" plus the service name
-traceEnabled - Boolean to enable/disable trace being passed back in exception
Defaults to "Y"
-docFormat - Format of the documentation for operations ("text" or "html").
Defaults to "text"
-stylesheet - The CSS stylesheet URL used in the HTML documentation
-errorCallback - Callback to be invoked in the event of an error being produced
-verifyUserArgs - Boolean to enable/disable validating user supplied arguments
Defaults to "N"
-enforceRequired - Throw an error if a required field is not included in the
response.
Defaults to "N"
</PRE>
<p><b>Returns</b> : Nothing </p>
<p><b>Side-Effects</b> : None </p>
<p><b>Exception Conditions</b> : </p><PRE> <i>MISSREQARG</i> -- Missing required arguments
</PRE>
<p><b>Pre-requisite Conditions</b> : None </p>
<HR>
<A name=Defining_an_Operation_.28aka_a_Service_Procedure.29></A>
<H2>Defining an Operation (aka a Service Procedure) </H2>
<p><b>Procedure Name : <i>::WS::Server::ServiceProc</i></b> </p>
<p><b>Description</b> : Register an operation for a service and declare the
procedure to handle the operations. </p>
<p><b>Arguments</b> : </p><PRE> <i>ServiceName </i> -- Name of the service this operation is for
<i>NameInfo </i> -- List of two elements:
1) OperationName -- the name of the operation
2) ReturnType -- the type of the procedure return,
this can be a simple or complex type
<i>Arglist </i> -- List of argument definitions,
each list element must be of the form:
1) ArgumentName -- the name of the argument
2) ArgumentTypeInfo -- -- A list of:
{type typeName comment commentString}
typeName can be any simple or defined type.
commentString is a quoted string describing the field
<i>Documentation</i> -- HTML describing what this operation does
<i>Body </i> -- The tcl code to be called when the operation is invoked. This
code should return a dictionary with <OperationName>Result as a
key and the operation's result as the value.
</PRE>
Available simple types are:
<UL><LI>anyType, string, boolean, decimal, float, double, duration, dateTime, time, date, gYearMonth, gYear, gMonthDay, gDay, gMonth, hexBinary, base64Binary, anyURI, QName, NOTATION, normalizedString, token, language, NMTOKEN, NMTOKENS, Name, NCName, ID, IDREF, IDREFS, ENTITY, ENTITIES, integer, nonPositiveInteger, negativeInteger, long, int, short, byte, nonNegativeInteger, unsignedLong, unsignedInt, unsignedShort, unsignedByte, positiveInteger</LI></UL>
The <em>typeName</em> may contain the following suffixes:
<UL>
<LI><em>()</em> : type is an array</LI>
<LI><em>?</em> : type is an optional parameter</LI>
</UL>
<p><b>Returns</b> : Nothing </p>
<p><i>Side-Effects</i> : </p><PRE> A procedure named "<ServiceName>::<OperationName>" defined
A type name with the name <OperationName>Result is defined.
</PRE>
<p><i>Exception Conditions</i> : None </p>
<p><i>Pre-requisite Conditions</i> : ::WS::Server::Server must have
been called for the ServiceName </p>
<HR>
<A name=Declaring_Complex_Types></A>
<H2>Declaring Complex Types </H2>
<p>See: <A
title="Creating a Web Service Type from Tcl"
href="Creating_a_Web_Service_Type.html">Creating
a Web Service Type from Tcl</A> </p>
</BODY>
</HTML>
|
