Differences From Artifact [70e97d53eb]:
- File
docs/Creating a Tcl Web Service.html
— part of check-in
[1a39cd9cf0]
at
2010-11-12 18:08:07
on branch proposed-main
— change eol-style to native
git-svn-id: http://tclws.googlecode.com/svn/trunk@65 4eab59b1-ed42-0410-973d-ab9b78d4c8bc (user: jeff@bovine.net@4eab59b1-ed42-0410-973d-ab9b78d4c8bc size: 7995)
To Artifact [8f85abdd95]:
- File
docs/Creating a Tcl Web Service.html
— part of check-in
[65d27d93eb]
at
2010-11-16 17:19:12
on branch proposed-main
— update documentation and comments
git-svn-id: http://tclws.googlecode.com/svn/trunk@83 4eab59b1-ed42-0410-973d-ab9b78d4c8bc (user: jeff@bovine.net@4eab59b1-ed42-0410-973d-ab9b78d4c8bc size: 9729)
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 |
<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>
</HEAD>
<BODY>
<H1>Creating a Tcl Web Service</H1>
<TABLE class=toc id=toc>
<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
| > | > > > > > | | | | | | | | | | | > > > > > > > > > > > > > > > > > | > > > > > | | | | | | | | | 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 |
<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>
</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
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:
|
| ︙ | ︙ | |||
100 101 102 103 104 105 106 |
cmd \
service \
operation \
caller_ipaddr \
http_header_list \
soap_header_list
-mode - Mode that service is running in. Must be one of:
| | | | | | > > > > > > > > > > | | | | | | | | | | | | | | | | | | | | 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 |
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
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 this call
-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"
</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 three elements:
1) OperationName -- the name of the operation
2) ReturnType -- the type of the procedure return,
this can be a simple or complex type
3) Description -- description of the return method
<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>
</BODY>
</HTML>
|