| <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Apache Rivet 3.0</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="next" href="installation.html" title="Apache Rivet 3.0 Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Apache Rivet 3.0</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="idm1"></a>Apache Rivet 3.0</h2></div><div><div class="author"><h3 class="author"><span class="firstname">The Rivet Team</span></h3><div class="affiliation"><span class="orgname">The Apache Software Foundation<br></span><div class="address"><p><br> | |
| <code class="email"><<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>></code><br> | |
| </p></div></div></div></div><div><p class="copyright">Copyright © 2002-2018 Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="index.html#introduction">Introduction to Apache Rivet version 3.0</a></span></dt><dt><span class="section"><a href="installation.html">Apache Rivet 3.0 Installation</a></span></dt><dt><span class="section"><a href="cmake.html">Building Rivet 3.0 with CMake</a></span></dt><dd><dl><dt><span class="section"><a href="cmake.html#idm185">CMake build procedure and examples</a></span></dt></dl></dd><dt><span class="section"><a href="directives.html">Apache Rivet 3.0 Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="directives.html#idm200">Apache Rivet Configuration lines</a></span></dt><dt><span class="section"><a href="directives.html#idm212">Configuration Directives</a></span></dt></dl></dd><dt><span class="section"><a href="processing.html">Apache Rivet HTTP Request Processing</a></span></dt><dd><dl><dt><span class="section"><a href="processing.html#idm574">Tcl Scripts Processing</a></span></dt><dt><span class="section"><a href="processing.html#idm583">Example: basic OO Rivet Application</a></span></dt></dl></dd><dt><span class="section"><a href="request.html">Apache Child Processes Lifecycle and Request Processing</a></span></dt><dt><span class="section"><a href="commands.html">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><dt><span class="section"><a href="commands.html#idm726"></a></span></dt><dt><span class="refentrytitle"><a href="shorthand.html"><?= ... ?></a></span><span class="refpurpose"> — | |
| Shorthand construct for single strings output | |
| </span></dt><dt><span class="refentrytitle"><a href="abort_code.html">abort_code</a></span><span class="refpurpose"> — | |
| Returns the code passed to <span style="font-family:monospace"><span class="command"><strong>abort_page</strong></span></span> | |
| earlier during the request processing | |
| </span></dt><dt><span class="refentrytitle"><a href="abort_page.html">abort_page</a></span><span class="refpurpose"> — | |
| Stops outputting data to web page, similar in | |
| purpose to PHP's <span style="font-family:monospace"><span class="command"><strong>die</strong></span></span> command. | |
| </span></dt><dt><span class="refentrytitle"><a href="apache_log_error.html">apache_log_error</a></span><span class="refpurpose"> — log messages to the Apache error log</span></dt><dt><span class="refentrytitle"><a href="apache_table.html">apache_table</a></span><span class="refpurpose"> — access and manipulate Apache tables in the request structure.</span></dt><dt><span class="refentrytitle"><a href="catch.html">catch</a></span><span class="refpurpose"> — wraps core command <span style="font-family:monospace"><span class="command"><strong>catch</strong></span></span> </span></dt><dt><span class="refentrytitle"><a href="clock_to_rfc.html">clock_to_rfc850_gmt</a></span><span class="refpurpose"> — create a rfc850 time from [clock seconds].</span></dt><dt><span class="refentrytitle"><a href="cookie.html">cookie</a></span><span class="refpurpose"> — get, set and delete cookies.</span></dt><dt><span class="refentrytitle"><a href="debug.html">debug</a></span><span class="refpurpose"> — | |
| A command to print strings, arrays | |
| and the values of variables as specified by the arguments. | |
| </span></dt><dt><span class="refentrytitle"><a href="env.html">env</a></span><span class="refpurpose"> — | |
| Loads a single "environmental variable" into a Tcl variable. | |
| </span></dt><dt><span class="refentrytitle"><a href="escape_sgml_chars.html">escape_sgml_chars</a></span><span class="refpurpose"> — escape special SGML characters in a string.</span></dt><dt><span class="refentrytitle"><a href="escape_shell_command.html">escape_shell_command</a></span><span class="refpurpose"> — escape shell metacharacters in a string.</span></dt><dt><span class="refentrytitle"><a href="escape_string.html">escape_string</a></span><span class="refpurpose"> — convert a string into escaped characters.</span></dt><dt><span class="refentrytitle"><a href="exit.html">exit</a></span><span class="refpurpose"> — terminate execution and child process</span></dt><dt><span class="refentrytitle"><a href="headers.html">headers</a></span><span class="refpurpose"> — set and parse HTTP headers.</span></dt><dt><span class="refentrytitle"><a href="html.html">html</a></span><span class="refpurpose"> — construct html tagged text.</span></dt><dt><span class="refentrytitle"><a href="http_accept.html">http_accept</a></span><span class="refpurpose"> — Parse HTTP Accept header lines</span></dt><dt><span class="refentrytitle"><a href="import_keyvalue_pairs.html">import_keyvalue_pairs</a></span><span class="refpurpose"> — Import an argument list into the named array</span></dt><dt><span class="refentrytitle"><a href="include.html">include</a></span><span class="refpurpose"> — includes a file into the output stream without modification.</span></dt><dt><span class="refentrytitle"><a href="incr0.html">incr0</a></span><span class="refpurpose"> — increment a variable or set it to 1 if nonexistent.</span></dt><dt><span class="refentrytitle"><a href="inspect.html">inspect</a></span><span class="refpurpose"> — Introspection command for Rivet configuration</span></dt><dt><span class="refentrytitle"><a href="lassign_array.html">lassign_array</a></span><span class="refpurpose"> — Assign a list of values to array variables</span></dt><dt><span class="refentrytitle"><a href="lempty.html">lempty</a></span><span class="refpurpose"> — | |
| Returns 1 if <list> is empty or 0 if it has any elements. | |
| This command emulates the TclX lempty command. | |
| </span></dt><dt><span class="refentrytitle"><a href="lmatch.html">lmatch</a></span><span class="refpurpose"> — | |
| Look for elements in <list> that match <pattern> | |
| </span></dt><dt><span class="refentrytitle"><a href="load_cookies.html">load_cookies</a></span><span class="refpurpose"> — get any cookie variables sent by the client.</span></dt><dt><span class="refentrytitle"><a href="load_env.html">load_env</a></span><span class="refpurpose"> — get the request's environment variables.</span></dt><dt><span class="refentrytitle"><a href="load_headers.html">load_headers</a></span><span class="refpurpose"> — get client request's headers.</span></dt><dt><span class="refentrytitle"><a href="load_response.html">load_response</a></span><span class="refpurpose"> — load form variables into an array.</span></dt><dt><span class="refentrytitle"><a href="lremove.html">lremove</a></span><span class="refpurpose"> — remove from a list elements matching one or more patterns</span></dt><dt><span class="refentrytitle"><a href="makeurl.html">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="no_body.html">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</span></dt><dt><span class="refentrytitle"><a href="parray.html">parray</a></span><span class="refpurpose"> — Tcl's <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> with html formatting.</span></dt><dt><span class="refentrytitle"><a href="parse.html">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</span></dt><dt><span class="refentrytitle"><a href="raw_post.html">raw_post</a></span><span class="refpurpose"> — get the unmodified body of a POST request sent by the client.</span></dt><dt><span class="refentrytitle"><a href="redirect.html">redirect</a></span><span class="refpurpose"> — Interrupt processing and divert to a new URL</span></dt><dt><span class="refentrytitle"><a href="read_file.html">read_file</a></span><span class="refpurpose"> — | |
| Read the entire contents of a file and return it as a string. | |
| </span></dt><dt><span class="refentrytitle"><a href="try.html">try</a></span><span class="refpurpose"> — | |
| Catch error and exception conditions | |
| </span></dt><dt><span class="refentrytitle"><a href="unescape_string.html">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a string.</span></dt><dt><span class="refentrytitle"><a href="upload.html">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</span></dt><dt><span class="refentrytitle"><a href="url_script.html">url_script</a></span><span class="refpurpose"> — get the code of the URL referenced Tcl script or Rivet template</span></dt><dt><span class="refentrytitle"><a href="var.html">var</a></span><span class="refpurpose"> — get the value of a form variable.</span></dt><dt><span class="refentrytitle"><a href="wrap.html">wrap</a></span><span class="refpurpose"> — | |
| Split a string on newlines. | |
| </span></dt><dt><span class="refentrytitle"><a href="wrapline.html">wrapline</a></span><span class="refpurpose"> — | |
| Split the line into multiple lines by splitting on space characters | |
| </span></dt><dt><span class="refentrytitle"><a href="xml.html">xml</a></span><span class="refpurpose"> — | |
| XML Fragments creation | |
| </span></dt></dl></dd><dt><span class="section"><a href="examples.html">Examples and Usage</a></span></dt><dt><span class="section"><a href="tcl_packages.html">Rivet Tcl Packages</a></span></dt><dt><span class="section"><a href="dio.html">DIO - Database Interface Objects</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="dio_package.html">DIO</a></span><span class="refpurpose"> — Database Interface Objects</span></dt></dl></dd><dt><span class="section"><a href="diodisplay.html">DIODisplay - Database Interface Objects Display Class</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="diodisplay_package.html">DIODisplay</a></span><span class="refpurpose"> — Database Interface Objects Display Class</span></dt></dl></dd><dt><span class="section"><a href="session_package.html">Session Package</a></span></dt><dd><dl><dt><span class="section"><a href="session_package.html#idm3241">Introduction</a></span></dt><dt><span class="section"><a href="session_package.html#requirements">Requirements</a></span></dt><dt><span class="section"><a href="session_package.html#idm3250">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#idm3260">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#idm3272">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#idm3318">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#idm3396">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#idm3452">Getting Additional Randomness From The Entropy File</a></span></dt></dl></dd><dt><span class="section"><a href="form.html">Form: An HTML Form Fields Generation Utility</a></span></dt><dd><dl><dt><span class="section"><a href="form.html#idm3458">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="form_package.html">form</a></span><span class="refpurpose"> — a Tcl command object for creating HTML forms</span></dt></dl></dd><dt><span class="section"><a href="calendar_package.html">Calendar Package</a></span></dt><dd><dl><dt><span class="section"><a href="calendar_package.html#idm3922">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="calendar.html">Calendar</a></span><span class="refpurpose"> — Utility class the builds and prints a calendar table</span></dt><dt><span class="refentrytitle"><a href="xml_calendar.html">XmlCalendar</a></span><span class="refpurpose"> — Prints XML formatted calendar tables</span></dt><dt><span class="refentrytitle"><a href="html_calendar.html">HtmlCalendar</a></span><span class="refpurpose"> — Concrete class derived from XmlCalendar</span></dt></dl></dd><dt><span class="section"><a href="entities.html">RivetEntities</a></span></dt><dd><dl><dt><span class="section"><a href="entities.html#idm4128">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="encode.html">encode</a></span><span class="refpurpose"> — | |
| encode a string replacing every occurrence of characters for | |
| which an SGML entity exists | |
| </span></dt><dt><span class="refentrytitle"><a href="decode.html">decode</a></span><span class="refpurpose"> — | |
| decode an SGML encoded string replacing every entity with the | |
| corresponding character | |
| </span></dt></dl></dd><dt><span class="section"><a href="asciiglyphs.html">AsciiGlyphs</a></span></dt><dd><dl><dt><span class="section"><a href="asciiglyphs.html#idm4168">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="toglyphs.html">toGlyphs</a></span><span class="refpurpose"> — | |
| print large ASCII glyphs | |
| </span></dt><dt><span class="section"><a href="asciiglyphs.html#idm4184">Example</a></span></dt></dl></dd><dt><span class="section"><a href="formbroker.html">The Form Broker</a></span></dt><dd><dl><dt><span class="section"><a href="formbroker.html#idm4189">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="fb.html">FormBroker</a></span><span class="refpurpose"> — | |
| Form broker object creator | |
| </span></dt></dl></dd><dt><span class="section"><a href="help.html">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="help.html#idm4317">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#idm4324">Newsgroup</a></span></dt><dt><span class="section"><a href="help.html#websites">Web Sites</a></span></dt><dt><span class="section"><a href="help.html#idm4344">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#idm4348">IRC</a></span></dt><dt><span class="section"><a href="help.html#idm4351">Editing Rivet Template Files</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Rivet Internals</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#idm4363">Rivet approach to Apache Multiprocessing Models</a></span></dt><dt><span class="section"><a href="internals.html#idm4376">mod_rivet MPM Bridge callbacks</a></span></dt><dt><span class="section"><a href="internals.html#idm4410">Server Initialization and MPM Bridge</a></span></dt><dt><span class="section"><a href="internals.html#idm4413">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#idm4418">The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</a></span></dt><dt><span class="section"><a href="internals.html#idm4426">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#idm4434">Extending Rivet by developing C code procedures</a></span></dt><dt><span class="section"><a href="internals.html#idm4458">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="lazybridge.html">Example: the <span class="quote">“<span class="quote">Lazy</span>”</span> bridge</a></span></dt><dd><dl><dt><span class="section"><a href="lazybridge.html#idm4488">The rationale of threaded bridges</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4492">Lazy bridge data structures</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4508">Handling Tcl's exit core command</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4527">HTTP request processing with the lazy bridge</a></span></dt></dl></dd></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>1. <a href="examples.html#hello_world">Hello World</a></dt><dt>2. <a href="examples.html#idm1932">Generate a Colorful Table</a></dt><dt>3. <a href="examples.html#variable_access">Variable Access</a></dt><dt>4. <a href="examples.html#file_upload">File Upload</a></dt><dt>5. <a href="examples.html#file_download">File Download</a></dt><dt>6. <a href="examples.html#ajax_xml_messaging">XML Messages and Ajax</a></dt><dt>7. <a href="examples.html#calendar_example">A Calendar Utility</a></dt></dl></div><p style="width:90%"> | |
| Document revision: $Revision: 1799149 $, last modified 2018-06-25 03:54:55+02:00$ by $Author: mxmanghi $. | |
| </p><div class="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction to Apache Rivet version 3.0</h2></div></div></div><p style="width:90%"> | |
| Apache Rivet is a system for creating dynamic web content by | |
| integrating the | |
| <a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl programming language</a> within the | |
| <a class="ulink" href="http://httpd.apache.org" target="_top">Apache Web Server</a>. | |
| It is designed to be fast, powerful and extensible, consume | |
| few system resources, be easy to learn, and to provide the user with a | |
| platform that can also be used for other programming tasks | |
| outside the web (GUI's, system administration tasks, text | |
| processing, database manipulation, XML, and so on). | |
| </p><p style="width:90%"> | |
| In this manual, we aim to help get you started, and then | |
| writing productive code as quickly as possible, as well as | |
| giving you ideas on how to best take advantage of Rivet's | |
| architecture to create different styles of web site. | |
| </p><p style="width:90%"> | |
| This documentation is focused on the current version of Rivet, but | |
| still a work in progress, and, like everything | |
| else about Apache Rivet, it is Free Software. If you see | |
| something that needs improving, and have ideas or suggestions, | |
| don't hesitate to let us know. If you want to contribute | |
| directly, better yet! | |
| </p><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm21"></a>Apache MPM and Rivet Bridge Modules</h3></div></div></div><p style="width:90%"> | |
| Rivet 3.0 is a major rewriting of mod_rivet, the Apache HTTP | |
| Websever module at the core of Rivet. Unlike in previous versions of | |
| mod_rivet which only supported the <a class="ulink" href="" target="_top">prefork MPM</a> | |
| (<a class="ulink" href="" target="_top">Multiprocessing Module</a>), | |
| starting with 3.0 we attained full support of different MPM for | |
| the Apache framework. | |
| </p><p style="width:90%"> | |
| Threaded <a class="ulink" href="" target="_top">MPM</a> | |
| integration was achieved by making mod_rivet multithreaded and | |
| modular itself, introducing the MPM-module bridge concept. | |
| We developed a set of loadable modules | |
| which are supposed not only to overcome the issues related to threading but also | |
| to offer the best possible MPM mod_rivet integration. | |
| As a side effect of this modular design mod_rivet is not only able to integrate | |
| with its environment but also to work as a framework for writing more MPM bridges | |
| designed along different multi-threading schemes and workload management models. | |
| See the <a class="link" href="internals.html" title="Rivet Internals">internals</a> section of this manual for | |
| further reading. MPM bridges are loaded accordingly to a heuristics of rules based | |
| on the Apache introspection calls but they can be determined in the configuration. | |
| Only a bridge can be loaded at a time. | |
| </p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm29"></a>Request Processing</h3></div></div></div><p style="width:90%"> | |
| Request processing was performed in mod_rivet version 2.x by chaining together 3 scripts | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">BeforeScript, if defined in the configuration</li><li class="listitem">The URI referenced Tcl script or rvt template dermined with | |
| respect to the <a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/core.html#documentroot" target="_top">DocumentRoot</a> and following | |
| other resource determination methods such the ones offered by | |
| <a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/mod_alias.html" target="_top">mod_alias</a> and by | |
| <a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html" target="_top">mod_rewrite</a>. | |
| </li><li class="listitem">AfterScript, if defined in the configuration</li></ul></div><p style="width:90%"> | |
| Errors and exceptions (raised by the <a class="link" href="abort_page.html" title="abort_page">::rivet::abort_page</a> command) | |
| are handled by the ErrorScript and AbortScript (ErrorScript has a default implementation | |
| if undefined in the configuration) | |
| </p><p style="width:90%"> | |
| Rivet 3.0 implements a new <a class="link" href="request.html" title="Apache Child Processes Lifecycle and Request Processing">request processing scheme</a> | |
| entirely based on Tcl. By default rivet 3.0 provides compatiblity with the | |
| version 2.x scheme to handle a request but this can be entirely overridden by | |
| the developer replacing the central request handling procedure. See the | |
| <a class="link" href="request.html" title="Apache Child Processes Lifecycle and Request Processing">request processing</a> page for further reading | |
| </p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm44"></a>Acknowledgements</h3></div></div></div><p style="width:90%">This version of Rivet received substantial contributions from George Petasis who solved | |
| several problems with the threaded code, improved the code in several ways and made the CMake | |
| based build scripts</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Apache Rivet 3.0 Installation</td></tr></table></div></body></html> |