Files changed (7)
- <para>The settings can also be defined using a python dictionnary instead of a file as follow :</para>
- <para>Before version 2.1, CherryPy was handling file uploads as follows: it was reading the entire file in memory, store it in a string and pass it to the method.
- When a file is being uploaded, this modules stores it in a temp file and returns a <code>FieldStorage</code> instance which contains information about this file.
- CherryPy then passes this <code>FieldStorage</code> instance to the method, this instance has the following attributes:</para>
- <para> On the first line we define that when the path <code>/entries/view</code> is called, or one
- <para>As all objects below <code>cherrypy.root.entries</code> will inherit the filter, there is no
- <para>CherryPy 2.1 includes a powerful sessions system provided via a new <literal>sessionFilter</literal>. </para>
- <para>First you need to enable the session filter through the configuration system, by setting <option>sessionFilter.on</option> to <literal>True</literal>. This gives you a variable called <literal>cherrypy.session</literal>, which is a dictionary-like object where you can read/store your session data. This dictionnary always has a special key called <literal>_id</literal> which contains the session id.</para>
- Specify which storage type should be used for storing session data on the server. Built-in types are <literal>Ram</literal> (default), <literal>File</literal> and <literal>PostgreSQL</literal> (see <xref linkend="backends"/> for more info)</para>
- The number of minutes of inactivity before an individual session can be removed. It can be a float (ex: 0.5 for 30 seconds). Defaults to 60.</para>
- Once in a while the server cleans up old/expired sessions. This config option specifies how often this clean up process should happe. The delay is in minutes. Defaults to 5.</para>
- The name of the cookie that CherryPy will use to store the session ID. Defaults to <literal>sessionID</literal>.</para>
- <para>CherryPy comes with multiple build-in backends for storing session data on the server side. They are:</para>
- All data is stored in RAM; this is the fastest storage, but it means that the data will be lost if you restart the server; and it also means that it won't scale to multiple processes/machines</para>
- All data is stored on disk; this is a bit slower than Ram storage, but the data will persist if you restart the server server; it also means that data can also be shared amongst multiple CherryPy processes (either on the same machine, or on multiple machines if all machines have access to the same disk ... through something like NFS for instance)</para>
- This backend is included with CherryPy to show how easy it is to implement your own custom backend for the session system. All data is stored in a PostgreSQL database; storing your data in a database is the recommend setup for production if you have a very high traffic website and you need to scale your site accross multiple machines. To use this backend you'll need to create the following table in your PostgreSQL database:
- You also need to programmatically set the <literal>sessionFilter.getDB</literal> config option to a function that returns a DB connection.
- <para>By default, CherryPy comes with 3 built-in backends, but if you have specific needs, it is very easy to implement your own custom backend (for instance, another database, or an XML-RPC server, ...). To do so, all you have to do is write a class that implements the following methods:
- Note that if you want to use <option>explicit</option> locking (see <xref linkend="concurrent"/>), you also have to implement two extra methods: <literal>acquireLock</literal> and <literal>releaseLock</literal>.
- <para>Once you have written this class, you have to programmatically set the <literal>sessionFilter.storageClass</literal> config option to this class.</para>
- <para>If you need help in writing your own custom backend it is a good idea to look at how the current ones (ram, file and postgresql) are implemented. They are implemented in the file <filename>cherrypy/lib/filter/sessionfilter.py</filename></para>
- <para>It is normally quite rare to have two simultaneous requests with the same session ID. It means that a same browser is making 2 requests to your server at the same time (to dynamic pages ... static data like images don't have sessions). However, this case can happen (if you're using frames for instance), and it will happen more and more often as more and more people start using Ajax.</para>
- <para>In that case, we need to make sure that access to the session data is serialized. This way threads can't both modify the data at the same time and leave it in an inconsistent state.</para>
- <para>By default, CherryPy will serialize access to the session data, so if a browser makes a second request while a first request is still being handled by the server, the second request will block while the first request is accessing the data. As soon as the first request is finished then the second request will be able to access it.</para>
- <para>This means that the second request will block until the first request is finished. If you're using the <option>ram</option> backend, you can manually shorten the window where the second request will block. This is achieved by having the first request explicitely tell CherryPy when it starts using the session data and when it is finished with it. In order to do so, you have to call <literal>cherrypy.session.acquireLock</literal> and <literal>cherrypy.session.releaseLock</literal>. You also have to set the <literal>sessionFilter.locking</literal> config option to <option>explicit</option>.</para>
- <para>Note that this technique only works with the <option>ram</option> backend. For other backends like <option>file</option> or <option>postgresql</option>, it is not safe to release the session before the request is finished, because the session data will only be saved at the end of the request anyway. So it would be bad if some other thread started accessing the data between the time when it is released and the time when it is saved.
- <para>It is possible to configure the <literal>sessionFilter</literal> so that it calls some special callback functions from your code when sessions are being created/deleted. To do so you have to set the <literal>sessionFilter.onCreateSession</literal> and <literal>sessionFilter.onDeleteSession</literal> config options. When a session is created/deleted, CherryPy will call these functions and pass them the session data.</para>
- <para>Static content is now handled by a filter called "staticFilter" that can easily be enabled and configured in your config file.
- For instance, if you wanted to serve <code>/style.css</code> from <filename>/home/site/style.css</filename> and <code>/static/*</code>
- <para>The <code>staticFilter.root</code> entry is not required; if you omit it, it defaults to the directory of your <code>cherrypy.root</code> class. </para>