Check-in [1ed3999e04]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Transfered some of the info in ticket [9c6ff35e39] about the 2.4 changes to the documentation. Restored stripping of a header from an xml response.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:1ed3999e04de1eb00965ad44d4015fd54a21332d
User & Date: oehhar 2017-08-30 08:53:38
Context
2017-08-31 08:41
Correct errors found by static analyser. Some documentation help for static analyser too check-in: 6e8f96d585 user: oehhar tags: trunk
2017-08-30 08:53
Transfered some of the info in ticket [9c6ff35e39] about the 2.4 changes to the documentation. Restored stripping of a header from an xml response. check-in: 1ed3999e04 user: oehhar tags: trunk
2017-04-11 16:21
Merge JSON REST changes into trunk. Ticket [9c6ff35e39] check-in: 2b869c069e user: gerald tags: trunk, Release_2.4.0
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to ServerSide.tcl.

1223
1224
1225
1226
1227
1228
1229

1230
1231
1232
1233
1234
1235
1236
....
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
....
1319
1320
1321
1322
1323
1324
1325





1326
1327
1328
1329
1330
1331
1332
# Description : Process the call to an operation.  If an error occurs, a standard
#               error packet is sent, otherwise the appropriate message type
#               is sent.
#
# Arguments :
#       serviceName     - The name of the service
#       sock            - The socket to return the WSDL on

#       args            - not used
#
# Returns :
#       1 - On error
#       0 - On success
#
# Side-Effects : None
................................................................................

    set ::errorInfo {}
    set ::errorCode {}
    set ns $service

    set inTransform $serviceInfo(-intransform)
    set outTransform $serviceInfo(-outtransform)
    # set first [string first {<} $inXML]
    # if {$first > 0} {
    #     set inXML [string range $inXML $first end]
    # }
    if {![string equal $inTransform  {}]} {
        set inXML [$inTransform REQUEST $inXML]
    }

    # Get a reference to the error callback
    set errorCallback $serviceInfo(-errorCallback)

    ##
................................................................................
                    # sanitize the JSONP callback function name for security.
                    set rawargs(jsonp_callback) FlightXmlCallback
                }
                set contentType "text/javascript"
            }
        }
        soap {





            # parse the XML request
            dom parse $inXML doc
            $doc documentElement top
            ::log::log debug [list $doc selectNodesNamespaces \
                                  [list ENV http://schemas.xmlsoap.org/soap/envelope/ \
                                       $service http://$serviceInfo(-host)$serviceInfo(-prefix)]]
            $doc selectNodesNamespaces \







>







 







<
<
<
<
|







 







>
>
>
>
>







1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
....
1288
1289
1290
1291
1292
1293
1294




1295
1296
1297
1298
1299
1300
1301
1302
....
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
# Description : Process the call to an operation.  If an error occurs, a standard
#               error packet is sent, otherwise the appropriate message type
#               is sent.
#
# Arguments :
#       serviceName     - The name of the service
#       sock            - The socket to return the WSDL on
#       -rest           - Use Rest flavor call instead of SOAP
#       args            - not used
#
# Returns :
#       1 - On error
#       0 - On success
#
# Side-Effects : None
................................................................................

    set ::errorInfo {}
    set ::errorCode {}
    set ns $service

    set inTransform $serviceInfo(-intransform)
    set outTransform $serviceInfo(-outtransform)




    if {$inTransform ne {}} {
        set inXML [$inTransform REQUEST $inXML]
    }

    # Get a reference to the error callback
    set errorCallback $serviceInfo(-errorCallback)

    ##
................................................................................
                    # sanitize the JSONP callback function name for security.
                    set rawargs(jsonp_callback) FlightXmlCallback
                }
                set contentType "text/javascript"
            }
        }
        soap {
            # skip any XML header
            set first [string first {<} $inXML]
            if {$first > 0} {
                set inXML [string range $inXML $first end]
            }
            # parse the XML request
            dom parse $inXML doc
            $doc documentElement top
            ::log::log debug [list $doc selectNodesNamespaces \
                                  [list ENV http://schemas.xmlsoap.org/soap/envelope/ \
                                       $service http://$serviceInfo(-host)$serviceInfo(-prefix)]]
            $doc selectNodesNamespaces \

Changes to docs/Creating_a_Tcl_Web_Service.html.

165
166
167
168
169
170
171






172
173
174
175
176
177
178
...
195
196
197
198
199
200
201











202
203
204
205
206
207
208
                              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>&nbsp;: Nothing </p>
<p><b>Side-Effects</b>&nbsp;: None </p>
<p><b>Exception Conditions</b>&nbsp;: </p><PRE>     <i>MISSREQARG</i> -- Missing required arguments
</PRE>
<p><b>Pre-requisite Conditions</b>&nbsp;: None </p>
<HR>
................................................................................
                                         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 &lt;OperationName&gt;Result as a
                            key and the operation's result as the value.
</PRE>











<p><b>Returns</b>&nbsp;: Nothing </p>
<p><i>Side-Effects</i>&nbsp;: </p><PRE>   A procedure named "&lt;ServiceName&gt;::&lt;OperationName&gt;" defined
   A type name with the name &lt;OperationName&gt;Result is defined.
</PRE>
<p><i>Exception Conditions</i>&nbsp;: None </p>
<p><i>Pre-requisite Conditions</i>&nbsp;:&nbsp;::WS::Server::Server must have
been called for the ServiceName </p>







>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>







165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
...
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
                              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>&nbsp;: Nothing </p>
<p><b>Side-Effects</b>&nbsp;: None </p>
<p><b>Exception Conditions</b>&nbsp;: </p><PRE>     <i>MISSREQARG</i> -- Missing required arguments
</PRE>
<p><b>Pre-requisite Conditions</b>&nbsp;: None </p>
<HR>
................................................................................
                                         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 &lt;OperationName&gt;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>&nbsp;: Nothing </p>
<p><i>Side-Effects</i>&nbsp;: </p><PRE>   A procedure named "&lt;ServiceName&gt;::&lt;OperationName&gt;" defined
   A type name with the name &lt;OperationName&gt;Result is defined.
</PRE>
<p><i>Exception Conditions</i>&nbsp;: None </p>
<p><i>Pre-requisite Conditions</i>&nbsp;:&nbsp;::WS::Server::Server must have
been called for the ServiceName </p>

Added docs/Rest_flavor_service_response.html.





















































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
<HTML lang=en dir=ltr xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<HEAD>
<TITLE>Rest-flavor service reply</TITLE>
<link rel="stylesheet" href="style.css" type="text/css" media="screen">
</HEAD>

<BODY>
<H1 class=firstHeading>Rest-flavor service reply</H1>

<HR>

<TABLE class=toc id=toc>
  <TR>
    <TD>
      <H2>Contents</H2></DIV>
      <UL>
        <LI class=toclevel-1><A href="#Overview"><SPAN class=tocnumber>1</SPAN> <SPAN class=toctext>Overview</SPAN></A>
        <LI class=toclevel-1><A href="#Rivet_Example"><SPAN
        class=tocnumber>2</SPAN> <SPAN class=toctext>Rivet example</SPAN></A>
      </UL></TD></TR></TBODY></TABLE>
<P>

</P>
<A name=Overview></A>
<H2>Overview </H2>
<P>Since TCLWS 2.4, it is possible to return a response in <em>REST style</em>.
This means, that a JSON reply is returned instead of an XML document.</P>
<P>Our use case has only required us to accept FORM arguments and return JSON responses for everything, so we haven't implemented logic to parse any input arguments that are passed in as JSON serialized data, but this might be an area of future exploration for someone.</P>

<A name=Rivet_Example></A>
<H2>Rivet Example</H2>
<P>Here's a bit of code showing how we initially start up this mode in Apache Rivet, which is actually pretty similar to how you'd use tclws in SOAP mode from Apache Rivet:</P>
<PRE>
        # Capture the info from the request into an array.
        load_headers hdrArray
        set sock [pid];         # an arbitrary value
        array unset ::Httpd$sock

        # Prepare the CGI style arguments into a list
        load_response formArray
        set opname $formArray(call)
        unset formArray(call)
        set queryarg [list $opname [array get formArray]]

        # Invoke the the method
        array set ::Httpd$sock [list query $queryarg ipaddr [env REMOTE_ADDR] headerlist [array get hdrArray]]

        # Invoke the method in REST mode.
        set result [catch {::WS::Server::callOperation $svcname $sock -rest} error]
        array unset ::Httpd$sock
        if {$result} {
                headers numeric 500
                puts "Operation failed: $error"
                abort_page
        }
</PRE>
</BODY>
</HTML>

Changes to docs/index.html.

19
20
21
22
23
24
25
26
27
28

29
30
31
32

33
34
35
36
37
38
39
..
66
67
68
69
70
71
72

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
currently works only with TclHttpd or embedded into an application.
The server side provides all services as document/literal
over HTTP Soap transport. Documentation for the package, including examples can
be found here.
</p>

<UL>
    <LI> <A HREF="Calling_a_Web_Service.html">Calling a Web Service from Tcl</A>
    <LI> <A HREF="Creating_a_Tcl_Web_Service.html">Creating a Tcl Web Service</A>
    <LI> <A HREF="Creating_a_Web_Service_Type.html">Creating a Web Service Type</A>

    <LI> <A HREF="Dictionary_Representation_of_XML_Arrays.html">Dictionary Representation of XML Arrays</A></LI>
    <LI> <A HREF="Using_Options.html">Using Web Service Options</A>
    <LI> <A HREF="Embedded_Web_Service.html">Embeding a Web Service into an application</A>
    <LI> <A HREF="Tcl_Web_Service_Example.html">Tcl Web Service Example</A>

</UL>

<p>
The client is known to work with #C and Java based Web Services (your mileage
may very).
</p>

................................................................................
 </li><li> <a href="http://www.tdom.org/">tdom 0.8.1</a>
 <li> dict (if tcl8.4 is used)</a> 
 </li><li> <a href="http://tls.sf.net/">tls</a> (client and embedded server)
 </li><li> log from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> uri from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> struct::set from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> http from <a href="http://tcl.sf.net/">Tcl</a> itself 

</li></ul>


<p>
Additionally, if you are running the TclHttpd on Windows, it is highly recommended that you use the iocpsock extension.
</p>

<p>
Lastly following packages are additionally used in Embedded Server mode:
</p><ul>
 <li> base64 from <a href="http://tcllib.sf.net/">TclLib</a> (also channel server)
 </li><li> html from <a href="http://tcllib.sf.net/">TclLib</a> (also channel server)
 </li><li> ncgi from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> fileutil from <a href="http://tcllib.sf.net/">TclLib</a>
</li></ul>
</BODY>
</HTML>







|
|
|
>

|
|
|
>







 







>




|



|








19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
..
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
currently works only with TclHttpd or embedded into an application.
The server side provides all services as document/literal
over HTTP Soap transport. Documentation for the package, including examples can
be found here.
</p>

<UL>
    <LI> <A HREF="Calling_a_Web_Service.html">Calling a Web Service from Tcl</A></LI>
    <LI> <A HREF="Creating_a_Tcl_Web_Service.html">Creating a Tcl Web Service</A></LI>
    <LI> <A HREF="Creating_a_Web_Service_Type.html">Creating a Web Service Type</A></LI>
	<LI> <A HREF="Rest_flavor_service_response.html">REST flavor service response</A></LI>
    <LI> <A HREF="Dictionary_Representation_of_XML_Arrays.html">Dictionary Representation of XML Arrays</A></LI>
    <LI> <A HREF="Using_Options.html">Using Web Service Options</A></LI>
    <LI> <A HREF="Embedded_Web_Service.html">Embeding a Web Service into an application</A></LI>
    <LI> <A HREF="Tcl_Web_Service_Example.html">Tcl Web Service Example</A></LI>
    <LI> <A HREF="Tcl_Web_Service_Math_Example.html">Tcl Web Service Math Example</A></LI>
</UL>

<p>
The client is known to work with #C and Java based Web Services (your mileage
may very).
</p>

................................................................................
 </li><li> <a href="http://www.tdom.org/">tdom 0.8.1</a>
 <li> dict (if tcl8.4 is used)</a> 
 </li><li> <a href="http://tls.sf.net/">tls</a> (client and embedded server)
 </li><li> log from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> uri from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> struct::set from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> http from <a href="http://tcl.sf.net/">Tcl</a> itself 
 </li><li> yajl-tcl from <a href="https://github.com/flightaware/yajl-tcl">flightaware github</a> (only for rest-flavour requests)
</li></ul>


<p>
If you are running the TclHttpd on Windows, it is highly recommended that you use the iocpsock extension.
</p>

<p>
The following packages are additionally used in Embedded Server mode:
</p><ul>
 <li> base64 from <a href="http://tcllib.sf.net/">TclLib</a> (also channel server)
 </li><li> html from <a href="http://tcllib.sf.net/">TclLib</a> (also channel server)
 </li><li> ncgi from <a href="http://tcllib.sf.net/">TclLib</a>
 </li><li> fileutil from <a href="http://tcllib.sf.net/">TclLib</a>
</li></ul>
</BODY>
</HTML>