193 lines
11 KiB
HTML
193 lines
11 KiB
HTML
<!-- BeginDsi "dsi/head.html" -->
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<title>Embedthis Appweb 4.3.4 Documentation</title>
|
|
<meta name="keywords" content="embedded web server, web server software, embedded HTTP, application web server,
|
|
embedded server, small web server, HTTP server, library web server, library HTTP, HTTP library" />
|
|
<meta name="description" content="Embedthis Sofware provides commercial and open source embedded web servers for
|
|
devices and applications." />
|
|
<meta name="robots" content="index,follow" />
|
|
<link href="../../../doc.css" rel="stylesheet" type="text/css" />
|
|
<link href="../../../print.css" rel="stylesheet" type="text/css" media="print"/>
|
|
<!--[if IE]>
|
|
<link href="../../../iehacks.css" rel="stylesheet" type="text/css" />
|
|
<![endif]-->
|
|
<link href="http://www.google.com/cse/style/look/default.css" type="text/css" rel="stylesheet" />
|
|
</head>
|
|
|
|
<body>
|
|
<div class="top">
|
|
<a class="logo" href="http://appwebserver.org/"> </a>
|
|
<div class="topRight">
|
|
<div class="search">
|
|
<div id="cse-search-form"></div>
|
|
<div class="version">Embedthis Appweb 4.3.4</div>
|
|
</div>
|
|
</div>
|
|
<div class="crumbs">
|
|
<a href="../../../index.html">Home</a>
|
|
<!-- EndDsi -->
|
|
><a href="index.html">ESP Guide</a> >
|
|
<b>Embedded Server Pages</b>
|
|
</div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="contentRight">
|
|
<h1>Quick Nav</h1>
|
|
<ul class="nav">
|
|
<li><a href="#sample">Sample Code</a></li>
|
|
<li><a href="#apis">ESP APIs</a></li>
|
|
<li><a href="#flash">Flash Storage</a></li>
|
|
<li><a href="#configuring">Configuring</a></li>
|
|
<li><a href="#performance">Performance</a></li>
|
|
</ul>
|
|
<!-- BeginDsi "dsi/webFrameSeeAlso.html" -->
|
|
<h1>See Also</h1>
|
|
<ul class="nav">
|
|
<li><a href="../../../guide/appweb/users/frameworks.html">Web Frameworks</a></li>
|
|
<li><a href="../../../guide/appweb/users/action.html">Action Handler</a></li>
|
|
<li><a href="../../../guide/appweb/users/cgi.html">CGI</a></li>
|
|
<li><a href="../../../guide/esp/users/index.html">ESP</a></li>
|
|
<li><a href="../../../guide/appweb/users/ejs.html">Ejscript</a></li>
|
|
<li><a href="../../../guide/appweb/users/php.html">PHP</a></li>
|
|
<li><a href="../../../guide/appweb/users/index.html">User Guide Overview</a></li>
|
|
<li><a href="../../../guide/appweb/users/configuration.html">Configuring Appweb</a></li>
|
|
<li><a href="../../../guide/appweb/users/ports.html">Ports and Binding</a></li>
|
|
<li><a href="../../../guide/appweb/users/authentication.html">User Authorization</a></li>
|
|
<li><a href="../../../guide/appweb/users/logFiles.html">Log Files</a></li>
|
|
<li><a href="../../../guide/appweb/users/vhosts.html">Virtual Hosts</a></li>
|
|
<li><a href="../../../guide/appweb/users/security.html">Security Considerations</a></li>
|
|
<li><a href="../../../guide/appweb/users/ssl.html">SSL</a></li>
|
|
<li><a href="../../../guide/appweb/users/modules.html">Appweb Modules</a></li>
|
|
<li><a href="../../../guide/appweb/users/stages.html">Pipeline Stages</a></li>
|
|
<li><a href="../../../guide/appweb/users/client.html">HTTP Client</a></li>
|
|
<li><a href="../../../ref/appweb/architecture.html">Appweb Architecture</a></li>
|
|
</ul>
|
|
<!-- EndDsi -->
|
|
</div>
|
|
<div class="contentLeft">
|
|
<h1>Session and Flash Storage</h1>
|
|
<p>Session storage is a limited, semi-permanent store for keeping state information across web requests.
|
|
The HTTP protocol by design, encourages stateless implementations and so Session state storage provides an
|
|
essential context for a series of requests.</p>
|
|
<p>Appweb provides a high performance, in-process session state store. The store is managed in that Appweb
|
|
imposes a session timeout on information and will automatically prune stale information. It uses the Appweb
|
|
memory limit configured by the <a href="../../appweb/users/dir/sandbox.html#limitMemory">LimitMemory</a>
|
|
directive to restrict the amount of memory that is devoted to session state.</p>
|
|
<a id="sample"></a>
|
|
<h2>Sample Code</h2>
|
|
<pre>
|
|
if (!(id = getSessionVar("user-id")) != 0) {
|
|
redirect("/login");
|
|
}
|
|
</pre>
|
|
<p>This example (above) tests if a "<em>user-id</em>" is defined in the session store. If not, the user must
|
|
login and is redirect to the login page.</p>
|
|
<pre>
|
|
destroySession();
|
|
createSession();
|
|
</pre>
|
|
<p>This forces the creation of a new session.</p>
|
|
<pre>
|
|
setSessionVar("Name", "John");
|
|
</pre>
|
|
<p>This defines the "<em>Name</em>" variable to the value "<em>John</em>".</p>
|
|
<a id="apis"></a>
|
|
<h2 class="section">ESP APIs</h2>
|
|
<p>The ESP session state API is comprised of four key APIs:
|
|
<ul>
|
|
<li><a href="../../../api/esp.html#group___esp_abbrev_1gab7b4049b554576b57f8cc49efc9e3a95">createSession</a></li>
|
|
<li><a href="../../../api/esp.html#group___esp_abbrev_1ga35677b9aa8d61543db5ea80377e823a6">destroySession</a></li>
|
|
<li><a href="../../../api/esp.html#group___esp_abbrev_1ga241f0cd4f5d49f8a137f1024415b2674">getSessionVar</a></li>
|
|
<li><a href="../../../api/esp.html#group___esp_abbrev_1gadb4f7bc3020ab9c481f1ebcaf1ed3f2a">setSessionVar</a></li>
|
|
</ul>
|
|
<a id="flash"></a>
|
|
<h2 class="section">Flash Storage</h2>
|
|
<p>ESP provides a traditional get/set key/value store. But it also provides a "flash" storage for passing
|
|
information to the next web request (only). Thereafter, the flash information is automatically removed.
|
|
Flash storage is useful to easily pass and manage feedback or notification messages for the next web page.
|
|
Using session state for this is problematic as the message can easily display on web pages other than the
|
|
immediate next web page. Flash storage will automatically remove the message after the next web page.</p>
|
|
<h3>Flash Types</h3>
|
|
<p>Flash messages are divided into different types:</p>
|
|
<ul>
|
|
<li>Errors — An error occurred and the operation failed.</li>
|
|
<li>Warnings — A warning has been issued, but the operation succeeded.</li>
|
|
<li>Informational — The operation succeeded and this is just for feedback.</li>
|
|
<li>Other — Any other kind of message.</li>
|
|
</ul>
|
|
<p>When ESP generates flash messages in a web page, it emits a CSS style corresponding to the message type.
|
|
This permits all errors to be flagged to the user using an "error" style. Similarly, for warnings and
|
|
informational errors.
|
|
<h3>Defining Flash Messages</h3>
|
|
<p>To issue a flash message for the next web page, use one of the APIs:
|
|
"<em>error</em>",
|
|
"<em>inform</em>",
|
|
"<em>warn</em>",
|
|
"<em>setFlash</em>",
|
|
<pre>
|
|
inform("Document saved");
|
|
warn("Session is about to expire in %d seconds", seconds);
|
|
error("Could not save document");
|
|
setFlash("custom", "Could not save document %s", myDocument);
|
|
</pre>
|
|
<p>You can use "<em>setFlash</em>" to define a custom type flash message using a type of your choosing.</p>
|
|
<h3>Displaying Flash Messages</h3>
|
|
<p>To display flash messages in a web page, use the
|
|
<a href="../../../api/esp.html#group___esp_abbrev_1ga8fd13fd70582fa020ad0dd5c00af5579">flash()</a> API.
|
|
<pre>
|
|
<% flash("all", NULL); %>
|
|
</pre>
|
|
<p>This will display all flash messages and then erase them from the flash store.</p>
|
|
<a id="configuring"></a>
|
|
<h2 class="section">Configuring Session</h2>
|
|
<p>Session data has a lifespan defined by the <a
|
|
href="../../appweb/users/dir/route.html#sessionTimeout">SessionTimeout</a> configuration file
|
|
directive. When this timeout expires, Appweb will prune the data from the session store.</p>
|
|
<p>If there is a low memory condition, Appweb may prune session data prematurely to free up memory.
|
|
The maximum memory limit may be configured by the
|
|
<a href="../../appweb/users/dir/sandbox.html#limitMemory">LimitMemory</a> configuration directive.</p>
|
|
<a id="performance"></a>
|
|
<h2 class="section">Performance Considerations</h2>
|
|
<h3>Minimize Session Data Size</h3>
|
|
<p>To maximize the performance of your application, try to minimize the size of data stored in the session
|
|
state store. Session data is copied to and from the store. Unnecessary copies will slow your
|
|
application.</p>
|
|
<h3>Minimize Session Data Reads and Writes</h3>
|
|
<p>It is important not to read from the session store repeatedly. During one request, try to read
|
|
session data once and keep a reference to the data for the duration of that request.</p>
|
|
</div>
|
|
</div>
|
|
<!-- BeginDsi "dsi/bottom.html" -->
|
|
<div class="bottom">
|
|
<p class="footnote">
|
|
<a href="../../../product/copyright.html" >© Embedthis Software LLC, 2003-2013.
|
|
All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.</a>
|
|
</p>
|
|
</div>
|
|
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
|
|
<script type="text/javascript">
|
|
google.load('search', '1', {language : 'en'});
|
|
google.setOnLoadCallback(function() {
|
|
var customSearchControl = new google.search.CustomSearchControl(
|
|
'000262706376373952077:1hs0lhenihk');
|
|
customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
|
|
var options = new google.search.DrawOptions();
|
|
options.enableSearchboxOnly("http://appwebserver.org/search.html");
|
|
customSearchControl.draw('cse-search-form', options);
|
|
}, true);
|
|
</script>
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-179169-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|