1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/sessions-usage.html Sat Apr 30 20:31:51 2005 +0000
1.3 @@ -0,0 +1,70 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Using Sessions</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Using Sessions</h1>
1.15 +<p>Unlike cookies, session information is always stored on the server
1.16 +and is not communicated back to the user. Consequently, sessions have
1.17 +several advantages over cookies, and the uses of sessions may include
1.18 +the storage of...</p>
1.19 +<ul>
1.20 + <li>Sensitive or private information. Although such information can
1.21 +be stored without needing to
1.22 +encrypt it, in many applications you will still want to
1.23 +encrypt such information anyway, no matter where it is stored or how it
1.24 +is communicated.</li>
1.25 + <li>Large amounts of session information can be stored, or at least
1.26 +larger amounts than are typically allowed using cookies.</li>
1.27 +</ul>
1.28 +<div class="WebStack">
1.29 +<h3>WebStack API - Using Sessions</h3>
1.30 +<p>In WebStack, a session appears as a dictionary to applications and
1.31 +is acquired for a specific user through the <a
1.32 + href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
1.33 +object. The following methods are provided in the transaction for
1.34 +accessing and maintenance of session information:</p>
1.35 +<dl>
1.36 + <dt><code>get_session</code></dt>
1.37 + <dd>This method returns the session for the identified user. The <code>create</code>
1.38 +parameter can be set to a true value to create a new session for a user
1.39 +if no session previously existed; otherwise <code>None</code> is
1.40 +returned in such situations.</dd>
1.41 + <dt><code>expire_session</code></dt>
1.42 + <dd>This method causes the session information associated with the
1.43 +identified user to be forgotten. Note that this may not really happen
1.44 +until the user sends another request, and that the <code>get_session</code>
1.45 +method may still return the current session.</dd>
1.46 +</dl>
1.47 +<p>Session objects, which resemble dictionaries, employ plain Python
1.48 +strings as keys in the accessing of information, and as the values
1.49 +loaded and stored inside the session. Unlike cookies, upon setting
1.50 +information within a session, such information is remembered thereafter
1.51 +without any other actions being necessary to make that information
1.52 +permanent or persistent.</p>
1.53 +<dl>
1.54 +</dl>
1.55 +</div>
1.56 +<h2>How and When to Access Sessions</h2>
1.57 +<p>To find out if a session has already been created, ask for a session
1.58 +by specifying that one should not be automatically created:</p>
1.59 +<pre> # In the respond method...<br /> session = trans.get_session(create=0) # session is None if no session already exists</pre>
1.60 +<p>To ensure that a session exists, just ask for a session:</p>
1.61 +<pre> # In the respond method...<br /> session = trans.get_session() # this is the same as using create=1</pre>
1.62 +<p>Session contents may mostly be accessed like dictionaries, so to
1.63 +access the keys within a session the following code could be used:</p>
1.64 +<pre> # In the respond method after obtaining a session...<br /> for key in session.keys():<br /> [Do something with the key - perhaps obtain values.]</pre>
1.65 +<p>To test the presence of a key, and to access values associated with
1.66 +a key, the usual dictionary methods apply:</p>
1.67 +<pre> # In the respond method after obtaining the session...<br /> if session.has_key("my_data"):<br /> my_data = session["my_data"]<br /> [Do something with my_data.]<br /> session["my_data"] = my_data</pre>
1.68 +<p>The session for the user may be removed or "expired" as follows:</p>
1.69 +<pre> # In the respond method...<br /> trans.expire_session()</pre>
1.70 +<p>Note that WebStack automatically knows which session is to be
1.71 +expired since only one such session can exist for the identified user.</p>
1.72 +</body>
1.73 +</html>