CGI::Session

CGI::Session

ri

 ---------------------------------------------------- Class: CGI::Session
      Class representing an HTTP session. See documentation for the file
      cgi/session.rb for an introduction to HTTP sessions.
 
 
 Lifecycle
 ---------
      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  new_session  option can be used to either
      always or never create a new session. See #new() for more details.
 
      #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.
 
 
 Setting and retrieving session data.
 ------------------------------------
      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).
 
      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.
 
 
 Storing session state
 ---------------------
      The caller can specify what form of storage to use for the
      session's data with the  database_manager  option to
      CGI::Session::new. The following storage classes are provided as
      part of the standard library:
 
      CGI::Session::FileStore:   stores data as plain text in a flat
                                 file. Only works with String data. This
                                 is the default storage type.
 
      CGI::Session::MemoryStore: stores data in an in-memory hash. The
                                 data only persists for as long as the
                                 current ruby interpreter instance does.
 
      CGI::Session::PStore:      stores data in Marshalled format.
                                 Provided by cgi/session/pstore.rb.
                                 Supports data of any type, and provides
                                 file-locking and transaction support.
 
      Custom storage types can also be created by defining a class with
      the following methods:
 
         new(session, options)
         restore  # returns hash of session data.
         update
         close
         delete
 
      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!
 
 
 Maintaining the session id.
 ---------------------------
      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.
 
      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.
 
      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.
 
 
 Examples of use
 ---------------
      Setting the user's name
        require 'cgi'
        require 'cgi/session'
        require 'cgi/session/pstore'     # provides CGI::Session::PStore
      
        cgi = CGI.new("html4")
      
        session = CGI::Session.new(cgi,
            'database_manager' => CGI::Session::PStore,  # use PStore
            'session_key' => '_rb_sess_id',              # custom session key
            'session_expires' => Time.now   30 * 60,     # 30 minute timeout
            'prefix' => 'pstore_sid_')                   # PStore option
        if cgi.has_key?('user_name') and cgi['user_name'] != ''
            # coerce to String: cgi[] returns the
            # string-like CGI::QueryExtension::Value
            session['user_name'] = cgi['user_name'].to_s
        elsif !session['user_name']
            session['user_name'] = "guest"
        end
        session.close
 
      Creating a new session safely
        require 'cgi'
        require 'cgi/session'
      
        cgi = CGI.new("html4")
      
        # We make sure to delete an old session if one exists,
        # not just to free resources, but to prevent the session
        # from being maliciously hijacked later on.
        begin
            session = CGI::Session.new(cgi, 'new_session' => false)
            session.delete
        rescue ArgumentError  # if no old session
        end
        session = CGI::Session.new(cgi, 'new_session' => true)
        session.close
 
 ------------------------------------------------------------------------
 
 
 Class methods:
 --------------
      new
 
 
 Instance methods:
 -----------------
      , =, close, create_new_id, delete, update
 
 Attributes:
      new_session, session_id

refe

 ==== CGI::Session ====
 [2001/08/26] by るびきち [URL:rubikitch@ruby-lang.org
 ---- Singleton methods ----
 ---- Instance methods ----
 ---- Singleton methods (inherited) ----
 ---- Instance methods (inherited) ----

  • 2006/05/15 12:03:11 at
  • 2006/05/12 19:55:09 CGI
  • 2006/05/12 19:55:49 CGI::Session
  • 2006/05/15 12:08:51 close
  • 2006/05/15 12:13:18 delete
  • 2006/05/15 12:42:14 new
  • 2006/05/15 12:52:33 restore
  • 2006/05/15 13:10:54 update
  • 2006/05/15 11:59:35 []
  • 2006/05/15 11:59:42 []=
  • 2006/05/15 11:59:52 ^