← Back
Editing: cdesc-Session.yaml
--- !ruby/object:RI::ClassDescription attributes: - !ruby/object:RI::Attribute comment: - !ruby/struct:SM::Flow::P body: The id of this session. name: new_session rw: R - !ruby/object:RI::Attribute comment: - !ruby/struct:SM::Flow::P body: The id of this session. name: session_id rw: R class_methods: - !ruby/object:RI::MethodSummary name: new comment: - !ruby/struct:SM::Flow::P body: Class representing an HTTP session. See documentation for the file cgi/session.rb for an introduction to HTTP sessions. - !ruby/struct:SM::Flow::H level: 2 text: Lifecycle - !ruby/struct:SM::Flow::P body: "A CGI::Session instance is created from a CGI object. By default, this CGI::Session instance will start a new session if none currently exists, or continue the current session for this client if one does exist. The <tt>new_session</tt> option can be used to either always or never create a new session. See #new() for more details." - !ruby/struct:SM::Flow::P body: "#delete() deletes a session from session storage. It does not however remove the session id from the client. If the client makes another request with the same id, the effect will be to start a new session with the old session's id." - !ruby/struct:SM::Flow::H level: 2 text: Setting and retrieving session data. - !ruby/struct:SM::Flow::P body: The Session class associates data with a session as key-value pairs. This data can be set and retrieved by indexing the Session instance using '[]', much the same as hashes (although other hash methods are not supported). - !ruby/struct:SM::Flow::P body: When session processing has been completed for a request, the session should be closed using the close() method. This will store the session's state to persistent storage. If you want to store the session's state to persistent storage without finishing session processing for this request, call the update() method. - !ruby/struct:SM::Flow::H level: 2 text: Storing session state - !ruby/struct:SM::Flow::P body: "The caller can specify what form of storage to use for the session's data with the <tt>database_manager</tt> option to CGI::Session::new. The following storage classes are provided as part of the standard library:" - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "CGI::Session::FileStore:" body: stores data as plain text in a flat file. Only works with String data. This is the default storage type. - !ruby/struct:SM::Flow::LI label: "CGI::Session::MemoryStore:" body: stores data in an in-memory hash. The data only persists for as long as the current ruby interpreter instance does. - !ruby/struct:SM::Flow::LI label: "CGI::Session::PStore:" body: stores data in Marshalled format. Provided by cgi/session/pstore.rb. Supports data of any type, and provides file-locking and transaction support. type: :NOTE - !ruby/struct:SM::Flow::P body: "Custom storage types can also be created by defining a class with the following methods:" - !ruby/struct:SM::Flow::VERB body: " new(session, options)\n restore # returns hash of session data.\n update\n close\n delete\n" - !ruby/struct:SM::Flow::P body: Changing storage type mid-session does not work. Note in particular that by default the FileStore and PStore session data files have the same name. If your application switches from one to the other without making sure that filenames will be different and clients still have old sessions lying around in cookies, then things will break nastily! - !ruby/struct:SM::Flow::H level: 2 text: Maintaining the session id. - !ruby/struct:SM::Flow::P body: Most session state is maintained on the server. However, a session id must be passed backwards and forwards between client and server to maintain a reference to this session state. - !ruby/struct:SM::Flow::P body: The simplest way to do this is via cookies. The CGI::Session class provides transparent support for session id communication via cookies if the client has cookies enabled. - !ruby/struct:SM::Flow::P body: If the client has cookies disabled, the session id must be included as a parameter of all requests sent by the client to the server. The CGI::Session class in conjunction with the CGI class will transparently add the session id as a hidden input field to all forms generated using the CGI#form() HTML generation method. No built-in support is provided for other mechanisms, such as URL re-writing. The caller is responsible for extracting the session id from the session_id attribute and manually encoding it in URLs and adding it as a hidden input to HTML forms created by other mechanisms. Also, session expiry is not automatically handled. - !ruby/struct:SM::Flow::H level: 2 text: Examples of use - !ruby/struct:SM::Flow::H level: 3 text: Setting the user's name - !ruby/struct:SM::Flow::VERB body: " require 'cgi'\n require 'cgi/session'\n require 'cgi/session/pstore' # provides CGI::Session::PStore\n\n cgi = CGI.new("html4")\n\n session = CGI::Session.new(cgi,\n 'database_manager' => CGI::Session::PStore, # use PStore\n 'session_key' => '_rb_sess_id', # custom session key\n 'session_expires' => Time.now + 30 * 60, # 30 minute timeout\n 'prefix' => 'pstore_sid_') # PStore option\n if cgi.has_key?('user_name') and cgi['user_name'] != ''\n # coerce to String: cgi[] returns the\n # string-like CGI::QueryExtension::Value\n session['user_name'] = cgi['user_name'].to_s\n elsif !session['user_name']\n session['user_name'] = "guest"\n end\n session.close\n" - !ruby/struct:SM::Flow::H level: 3 text: Creating a new session safely - !ruby/struct:SM::Flow::VERB body: " require 'cgi'\n require 'cgi/session'\n\n cgi = CGI.new("html4")\n\n # We make sure to delete an old session if one exists,\n # not just to free resources, but to prevent the session\n # from being maliciously hijacked later on.\n begin\n session = CGI::Session.new(cgi, 'new_session' => false)\n session.delete\n rescue ArgumentError # if no old session\n end\n session = CGI::Session.new(cgi, 'new_session' => true)\n session.close\n" constants: [] full_name: CGI::Session includes: [] instance_methods: - !ruby/object:RI::MethodSummary name: "[]" - !ruby/object:RI::MethodSummary name: "[]=" - !ruby/object:RI::MethodSummary name: close - !ruby/object:RI::MethodSummary name: create_new_id - !ruby/object:RI::MethodSummary name: delete - !ruby/object:RI::MethodSummary name: update name: Session superclass: Object
Save File
Cancel