D 2012-10-31T06:33:59.060
L WSServer\sServer\sSide
P 7e6f53118e2149470c779cc2f7c705bacbe38b02
U gerald
W 10564
<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> -host - The host name for this service
Defaults to "localhost"
-description - The HTML description for this service
-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
</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>
<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>
Z 12db3ffe15832fcc8353ea172a118cbe