| paulb@360 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| paulb@470 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head> |
| paulb@360 | 3 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
| paulb@470 | 4 | |
| paulb@470 | 5 | <title>Using Sessions</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
| paulb@470 | 6 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
| paulb@470 | 7 | |
| paulb@360 | 8 | <body> |
| paulb@360 | 9 | <h1>Using Sessions</h1> |
| paulb@360 | 10 | <p>Unlike cookies, session information is always stored on the server |
| paulb@360 | 11 | and is not communicated back to the user. Consequently, sessions have |
| paulb@360 | 12 | several advantages over cookies, and the uses of sessions may include |
| paulb@360 | 13 | the storage of...</p> |
| paulb@360 | 14 | <ul> |
| paulb@360 | 15 | <li>Sensitive or private information. Although such information can |
| paulb@360 | 16 | be stored without needing to |
| paulb@360 | 17 | encrypt it, in many applications you will still want to |
| paulb@360 | 18 | encrypt such information anyway, no matter where it is stored or how it |
| paulb@360 | 19 | is communicated.</li> |
| paulb@360 | 20 | <li>Large amounts of session information can be stored, or at least |
| paulb@360 | 21 | larger amounts than are typically allowed using cookies.</li> |
| paulb@360 | 22 | </ul> |
| paulb@360 | 23 | <div class="WebStack"> |
| paulb@360 | 24 | <h3>WebStack API - Using Sessions</h3> |
| paulb@360 | 25 | <p>In WebStack, a session appears as a dictionary to applications and |
| paulb@470 | 26 | is acquired for a specific user through the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a> |
| paulb@360 | 27 | object. The following methods are provided in the transaction for |
| paulb@360 | 28 | accessing and maintenance of session information:</p> |
| paulb@360 | 29 | <dl> |
| paulb@360 | 30 | <dt><code>get_session</code></dt> |
| paulb@360 | 31 | <dd>This method returns the session for the identified user. The <code>create</code> |
| paulb@360 | 32 | parameter can be set to a true value to create a new session for a user |
| paulb@360 | 33 | if no session previously existed; otherwise <code>None</code> is |
| paulb@360 | 34 | returned in such situations.</dd> |
| paulb@360 | 35 | <dt><code>expire_session</code></dt> |
| paulb@360 | 36 | <dd>This method causes the session information associated with the |
| paulb@360 | 37 | identified user to be forgotten. Note that this may not really happen |
| paulb@360 | 38 | until the user sends another request, and that the <code>get_session</code> |
| paulb@360 | 39 | method may still return the current session.</dd> |
| paulb@360 | 40 | </dl> |
| paulb@360 | 41 | <p>Session objects, which resemble dictionaries, employ plain Python |
| paulb@360 | 42 | strings as keys in the accessing of information, and as the values |
| paulb@360 | 43 | loaded and stored inside the session. Unlike cookies, upon setting |
| paulb@360 | 44 | information within a session, such information is remembered thereafter |
| paulb@360 | 45 | without any other actions being necessary to make that information |
| paulb@360 | 46 | permanent or persistent.</p> |
| paulb@360 | 47 | <dl> |
| paulb@360 | 48 | </dl> |
| paulb@360 | 49 | </div> |
| paulb@360 | 50 | <h2>How and When to Access Sessions</h2> |
| paulb@360 | 51 | <p>To find out if a session has already been created, ask for a session |
| paulb@360 | 52 | by specifying that one should not be automatically created:</p> |
| paulb@360 | 53 | <pre> # In the respond method...<br /> session = trans.get_session(create=0) # session is None if no session already exists</pre> |
| paulb@360 | 54 | <p>To ensure that a session exists, just ask for a session:</p> |
| paulb@360 | 55 | <pre> # In the respond method...<br /> session = trans.get_session() # this is the same as using create=1</pre> |
| paulb@360 | 56 | <p>Session contents may mostly be accessed like dictionaries, so to |
| paulb@360 | 57 | access the keys within a session the following code could be used:</p> |
| paulb@360 | 58 | <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> |
| paulb@360 | 59 | <p>To test the presence of a key, and to access values associated with |
| paulb@360 | 60 | a key, the usual dictionary methods apply:</p> |
| paulb@360 | 61 | <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> |
| paulb@360 | 62 | <p>The session for the user may be removed or "expired" as follows:</p> |
| paulb@360 | 63 | <pre> # In the respond method...<br /> trans.expire_session()</pre> |
| paulb@360 | 64 | <p>Note that WebStack automatically knows which session is to be |
| paulb@360 | 65 | expired since only one such session can exist for the identified user.</p> |
| paulb@470 | 66 | <h2>Session Limitations and Guidelines</h2> |
| paulb@470 | 67 | <ul> |
| paulb@470 | 68 | <li>Due to various limitations in the storage of session information, |
| paulb@470 | 69 | it is recommended that each item of data is converted to a string value |
| paulb@470 | 70 | when being set in the session, and that the key employed is also a |
| paulb@470 | 71 | string value. These limitations may be removed in a later release.</li> |
| paulb@470 | 72 | </ul> |
| paulb@470 | 73 | |
| paulb@470 | 74 | </body></html> |
