9 | This is some text. The image is generated a CGI script so
10 | we can hopefully see two threads dispatched to do work as the CGI
11 | script blocks.
12 |
13 | This page shows the very simple processing done
14 | for page.subst pages.
15 | These pages process Tcl embedded in pages,
16 | but don't have the more sophisticated support developed
17 | for the page.tml pages.
18 |
19 |
The time is [clock format [clock seconds]]
20 |
21 | Here is a look inside the httpd server module.
22 | This is generated with the html::tableFromArray command
23 | applied to the Httpd array variable in the server.
24 |
25 | [html::tableFromArray Httpd]
26 |
27 |
28 |
29 |
30 |
--------------------------------------------------------------------------------
/Examples/README.txt:
--------------------------------------------------------------------------------
1 | The file EchoWebService.tcl defines a service and should be sourced in by the web services server. Normally this is done by placing it in the custom directory.
2 |
3 |
4 | The file CallEchoWebService.tcl is a Tcl script (i.e. non-GUI) designed to show how calls can be made.
5 |
6 | The file htdocs/service/index.tml should be copied to service/index.tml under the document root of the web server (normally htdocs). This page when displayed in a browser as http://localhost:8015/service/ will show a nice page listing what services you have available. The page will dynamically generate links to the info and wsdl pages that the server generates and also to status pages (located in http://localhost:8015/servicestatus/$serviceName.tml) and form pages (located in http://localhost:8015/serviceforms/$serviceName.tml).
7 |
8 | This would allow you to auto generate, or hand generate, forms to call your service operations and also status pages to monitor and control your services.
9 |
10 | Alternatively, the following could be done from the current directory (assuming that httpd.tcl is in the current PATH):
11 | httpd.tcl -docRoot ./tclhttpd/htdocs -port 8015 -library ./tclhttpd/custom/
12 |
--------------------------------------------------------------------------------
/WubServer.tcl:
--------------------------------------------------------------------------------
1 | # WSWub - Wub interface to WebServices
2 | package require Tcl 8.4-
3 | # WS::Utils usable here for dict?
4 | if {![llength [info command dict]]} {
5 | package require dict
6 | }
7 | package require WS::Server
8 |
9 | package require OO
10 | package require Direct
11 | package require Debug
12 | Debug off wsdl 10
13 |
14 | package provide WS::Wub 2.5.0
15 | package provide Wsdl 2.4.0
16 |
17 | class create Wsdl {
18 | method / {r args} {
19 | return [Http Ok $r [::WS::Server::generateInfo $service 0] text/html]
20 | }
21 |
22 | method /op {r args} {
23 | if {[catch {::WS::Server::callOp $service 0 [dict get $r -entity]} result]} {
24 | return [Http Ok $r $result]
25 | } else {
26 | dict set r -code 500
27 | dict set r content-type text/xml
28 | dict set r -content $result
29 | return [NoCache $r]
30 | }
31 | }
32 |
33 | method /wsdl {r args} {
34 | return [Http Ok $r [::WS::Server::GetWsdl $service] text/xml]
35 | }
36 |
37 | mixin Direct ;# Direct mixin maps the URL to invocations of the above methods
38 | variable service
39 | constructor {args} {
40 | set service [dict get $args -service] ;# we need to remember the service name
41 | }
42 | }
43 |
--------------------------------------------------------------------------------
/Examples/tclhttpd/htdocs/templates/form.tml:
--------------------------------------------------------------------------------
1 | [html::author "Brent Welch"]
2 | [mypage::header "Templates and State"]
3 | Sample Form
4 |
5 |
46 |
47 |
48 | [mypage::footer]
49 |
--------------------------------------------------------------------------------
/Examples/tclhttpd/htdocs/templates/self.tml:
--------------------------------------------------------------------------------
1 | [::learn::header "Tcl in your Page"]
2 | [Doc_Dynamic]
3 |
4 | This page shows what you can do with a little bit of Tcl code in a page.
5 |
6 |
10 |
21 | Right below the <hr> horizontal line we'll display the
22 | result of the Example1 procedure:
23 |
34 | The body of the Example1 procedure is shown here.
35 |
46 | Hint if there is no procedure, try
47 | return "<b>\[clock format \[clock seconds\]\]</b>"
48 |
49 | Understand that this code runs with all the powers of the
50 | web server application. If you want to halt the server, try this.
51 |
52 | exit
53 |
54 | Ha! tried it, huh? This page runs Example1 in a Safe-Tcl interpreter,
55 | although the TML template system normally runs the templates in
56 | the main interpreter of your application.
57 | [mypage::footer]
58 |
--------------------------------------------------------------------------------
/Examples/wub/WubApp.tcl:
--------------------------------------------------------------------------------
1 | #! /usr/bin/env tclsh
2 | lappend ::auto_path [file dirname [info script]]
3 | lappend ::auto_path ../Wub/Wub/ ;# add Wub's directory to auto_path
4 | package require WS::Server
5 |
6 | ##
7 | ## Define the service
8 | ##
9 | ::WS::Server::Service -mode wub \
10 | -htmlhead {Wub Based Web Services} \
11 | -service wsEchoExample \
12 | -description {Echo Example - Tcl Web Services} \
13 | -ports 8080
14 |
15 | ##
16 | ## Define any special types
17 | ##
18 | ::WS::Utils::ServiceTypeDef Server wsEchoExample echoReply {
19 | echoBack {type string}
20 | echoTS {type dateTime}
21 | }
22 |
23 | ##
24 | ## Define the operations available
25 | ##
26 | ::WS::Server::ServiceProc \
27 | wsEchoExample \
28 | {SimpleEcho {type string comment {Requested Echo}}} \
29 | {
30 | TestString {type string comment {The text to echo back}}
31 | } \
32 | {Echo a string back} {
33 |
34 | return [list SimpleEchoResult $TestString]
35 | }
36 |
37 | ::WS::Server::ServiceProc \
38 | wsEchoExample \
39 | {ComplexEcho {type echoReply comment {Requested Echo -- text and timestamp}}} \
40 | {
41 | TestString {type string comment {The text to echo back}}
42 | } \
43 | {Echo a string and a timestamp back} {
44 |
45 | set timeStamp [clock format [clock seconds] -format {%Y-%m-%dT%H:%M:%SZ} -gmt yes]
46 | return [list ComplexEchoResult [list echoBack $TestString echoTS $timeStamp] ]
47 | }
48 |
49 | #### Wub specific application start
50 | package require Site ;# load up the site
51 |
52 | # Initialize Site
53 | Site init home [file normalize [file dirname [info script]]] ini site.ini debug 10
54 |
55 | # this defines the mapping from URL to Wsdl interface objects
56 | package require Nub
57 | package require WS::Wub
58 | Nub domain /service/wsEchoExample Wsdl -service wsEchoExample
59 | Nub domain /service/wsEchoExample2 Wsdl -service wsEchoExample ;# you can have multiple Wsdl instances
60 |
61 | # Start Site Server(s)
62 | Site start
63 |
--------------------------------------------------------------------------------
/Examples/tclhttpd/htdocs/templates/faqfaq.tml:
--------------------------------------------------------------------------------
1 | [html::description "tclhttpd FAQ generator FAQ"]
2 | [html::keywords ]
3 | [html::author "Colin McCormack"]
4 | [mypage::header "tclhttpd FAQ generator FAQ"]
5 |
6 | [FAQinit "tclhttpd FAQ FAQ"]
7 |
8 |
52 |
53 | [FAQgen]
54 |
55 | [mypage::footer]
56 |
--------------------------------------------------------------------------------
/license.terms:
--------------------------------------------------------------------------------
1 | This software is copyrighted by the Gerald W. Leser and other parties. The following terms apply to all files
2 | associated with the software unless explicitly disclaimed in
3 | individual files.
4 |
5 | The authors hereby grant permission to use, copy, modify, distribute,
6 | and license this software and its documentation for any purpose, provided
7 | that existing copyright notices are retained in all copies and that this
8 | notice is included verbatim in any distributions. No written agreement,
9 | license, or royalty fee is required for any of the authorized uses.
10 | Modifications to this software may be copyrighted by their authors
11 | and need not follow the licensing terms described here, provided that
12 | the new terms are clearly indicated on the first page of each file where
13 | they apply.
14 |
15 | IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
16 | FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
17 | ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
18 | DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
19 | POSSIBILITY OF SUCH DAMAGE.
20 |
21 | THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
22 | INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
23 | FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
24 | IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
25 | NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
26 | MODIFICATIONS.
27 |
28 | GOVERNMENT USE: If you are acquiring this software on behalf of the
29 | U.S. government, the Government shall have only "Restricted Rights"
30 | in the software and related documentation as defined in the Federal
31 | Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
32 | are acquiring the software on behalf of the Department of Defense, the
33 | software shall be classified as "Commercial Computer Software" and the
34 | Government shall have only "Restricted Rights" as defined in Clause
35 | 252.227-7014 (b) (3) of DFARs. Notwithstanding the foregoing, the
36 | authors grant the U.S. Government and others acting in its behalf
37 | permission to use and distribute the software in accordance with the
38 | terms specified in this license.
39 |
--------------------------------------------------------------------------------
/docs/Rest_flavor_service_response.html:
--------------------------------------------------------------------------------
1 |
2 |
3 | Rest-flavor service reply
4 |
5 |
6 |
7 |
8 |
Since TCLWS 2.4, it is possible to return a response in REST style.
27 | This means, that a JSON reply is returned instead of an XML document.
28 |
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.
29 |
30 |
31 |
Rivet Example
32 |
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:
33 |
34 | # Capture the info from the request into an array.
35 | load_headers hdrArray
36 | set sock [pid]; # an arbitrary value
37 | array unset ::Httpd$sock
38 |
39 | # Prepare the CGI style arguments into a list
40 | load_response formArray
41 | set opname $formArray(call)
42 | unset formArray(call)
43 | set queryarg [list $opname [array get formArray]]
44 |
45 | # Invoke the the method
46 | array set ::Httpd$sock [list query $queryarg ipaddr [env REMOTE_ADDR] headerlist [array get hdrArray]]
47 |
48 | # Invoke the method in REST mode.
49 | set result [catch {::WS::Server::callOperation $svcname $sock -rest} error]
50 | array unset ::Httpd$sock
51 | if {$result} {
52 | headers numeric 500
53 | puts "Operation failed: $error"
54 | abort_page
55 | }
56 |
8 | This server has the interesting ability to reload parts of its implementation
9 | dynamically. This lets you add features and fix bugs without ever
10 | restarting.
11 | It is even possible to setup a debug session with TclPro.
12 | This is made possible with the help of the /debug URL. The debug module
13 | has e.g. several useful URLs that let you examine variable values and other internal state.
14 |
15 |
40 | For more specific information about the calls see the debug module.
41 |
42 | Some examples:
43 |
44 |
47 |
48 |
51 |
52 |
53 |
56 |
57 |
TclPro
58 | It is also possible to debug tclhttpd with TclPro.
59 | Briefly you have to perform following steps:
60 |
61 | Enable the tclhttpd server for debugging (see httpdthread.tcl).
62 |
63 | Setup a Project in TclPro with Debugging Type "Remote Debugging";
64 | define the portnumber; start TclPro by calling
65 |
68 | The tclhttpd server will connect to a TclPro Session running on host <hostname>
69 | listening for remote connections on port number <portnumber>
70 |
71 | In case TclPro is running on the "localhost" listening for the default portnumber "2576"
72 | it is enough to call
73 |
74 | http://yourserver:port/debug/dbg
75 |
76 | [mypage::footer]
77 |
--------------------------------------------------------------------------------
/docs/Dictionary_Representation_of_XML_Arrays.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Web Services for Tcl (aka tclws): Dictionary Representation of XML Arrays
5 |
6 |
7 |
8 |
9 | XML arrays are represented in dictionary format as a list of values.
10 | Lets consider what this looks like for a
11 | simple type and for a
12 | complex type;.
13 |
14 |
15 |
16 |
Array of Simple Type
17 |
18 | Lets assume we have an element with the following definition:
19 |
21 | Lets also assume that we will have that element in our dictionary with
22 | the first four prime numbers, thus the dictionary representation for
23 | that element would look like:
24 |
Primes {2 3 5 7}
25 |
26 | Or, if we have are using attributes (i.e. parseInAttr and/or genOutAttr are set), it would look like:
27 |
Primes {{} {2 3 5 7}}
28 |
29 |
30 |
31 |
32 |
Array of Complex Type
33 |
34 | Lets assume we have the type definition:
35 |
3 | A Tcl template works by mixing Tcl code into normal HTML pages.
4 | The server uses the Tcl subst command to replace the Tcl code and
5 | variable references with their results and values.
6 | Here are a few examples:
7 |
19 | There are two template systems provided by the Doc module:
20 | tml and subst templates. They both work
21 | in a similar way to replace in-line Tcl,
22 | but they differ in the setup done before a page is processed.
23 |
24 |
25 |
26 | If you have a file
27 | that ends with ".subst",
28 | then it is processed every time the page is fetched.
29 | There is relatively little setup done before processing the page.
30 |
31 |
32 |
tml Templates
33 | The ".tml" template system is similar to the ".subst" system,
34 | but it provides caching and additional
35 | setup before pages are processed.
36 |
37 |
Caching Template Results
38 |
39 | The ".tml" template system provides caching of template results
40 | in static ".html" files. This saves the cost of re-processing the
41 | template each time you access the file.
42 | By default, the file page.html contains the cached results
43 | of processing the file page.tml. If the page.tml
44 | page is modified, the cached copy is regenerated. To get the
45 | cache, you have to ask for the page.html file. The server
46 | automatically checks to see if there is a corresponding page.tml
47 | file, processes the template, caches the result in page.html,
48 | and returns the result.
49 |
50 | However, you don't want
51 | to cache if the page must be processed on each access.
52 | If you don't want your templates cached, put a call to
53 |
\[Doc_Dynamic\]
54 | into your page. That surpresses the caching of the template results.
55 |
56 |
Per-directory .tml files
57 |
58 | Before processing a page.tml page, the server loads
59 | any file named ".tml" (no prefix) in the same directory.
60 | This allows you to put procedure and variable definitions in
61 | the ".tml" file that are shared among the pages in that directory.
62 |
63 | The server looks up the directory hierarchy to the document root
64 | for additional ".tml" files. These are all loaded in order from the
65 | root down towards the directory containing the template file page.tml.
66 | If you look at the sample htdocs tree that comes with the server,
67 | you can see how these .tml files are used.
68 |
69 |
FAQ Generator example that illustrates
75 | how to use
76 | the faq module in the sample custom directory.
77 |
78 |
Templates with Form Data
79 | If you want to process query data, it is available via the ncgi
80 | interface, and indirectly via the html interface used
81 | to create form elements.
82 |
83 |
17 | 
19 | 
"]