HTTP::Daemon::Threaded::Session

SUMMARY: CONSTR | METHOD | DETAIL: CONSTR | METHOD

## Class HTTP::Daemon::Threaded::Session

Abstract base class for Session classes. Provides an interface definition for a single threads::shared session context container. Loosely based on the Java Servlets HttpSession class.

Note: This implementation does not provide interfaces for user authorization/authentication. The intent is to outsource such functionality to the application level, which can populate and retrieve attributes as needed, and apply any encryption or privileges in an application specific manner. Future releases may provide stock objects providing common auth&auth functionality.

Note2: The default implementation does not support Set-Cookie2/Cookie2 HTTP headers.

Copyright© 2006, Dean Arnold, Presicient Corp., USA
All rights reserved.

Licensed under the Academic Free License version 2.1, as specified in the License.txt file included in this software package, or at OpenSource.org.

Author:
  D. Arnold
Version:
  0.90
Since:
  2006-08-21
See Also:
  Java Servlets

Unless otherwise noted, `$self` is the object instance variable.

Constructor Summary
`new($cache, $id, $timeout, $dough, $expires)` Uses input ID, Inactivity timeout, cookie "dough" and expiration timestamp to create a new session context
`open($id, $cache)` Uses input identifier to load a session context from persistent storage

Method Summary
`close()` Closes this session and removes it from the parent SessionCache
`cookieSent()` Called to indicate that the cookie has been sent to the client
`getAttribute($name)` Returns the object bound with the specified name
`getAttributeNames()` Returns the list of attributes bound to this session
`getCookie()` Returns this session's cookie
`getCreationTime()` Returns the creation time of this session as a fractional number
`getExpiration()` Get expiration on this session
`getID()` Returns the unique ID time of this session NOTE: As a read operation on a static value, no lock is required
`getLastAccessedTime()` Returns the last time the client sent a request for this session
`getMaxInactiveInterval()` Returns the last time the client sent a request for this session
`isInactive()` Has this session timed out ?
`isNew()` Returns true if the cookie for the session has not yet been sent to the client
`removeAttribute($name)` Removes the object bound to the specified name from this session
`setAttribute($name, $value)` Set an attribute on this session, using the name specified
`setExpiration($expires)` Set expiration on this session
`setLastAccessedTime()` Set the last time the client sent a request for this session
`setMaxInactiveInterval($timeout)` Set the max inactivity interval, in seconds, for this session

Constructor Details

### open

    open($id, $cache)

  Uses input identifier to load a session context from persistent storage.

  NOTE: this default implementation simply returns undef, as it does not use persistent storage

  Parameters:
    `$id` - unique identifier for the session to be recovered
    `$cache` - parent SessionCache object
  Returns:
    undef if the session cannot be recovered, otherwise, the HTTP::Daemon::Threaded::Session object

### new

    new($cache, $id, $timeout, $dough, $expires)

  Uses input ID, Inactivity timeout, cookie "dough" and expiration timestamp to create a new session context.

  Parameters:
    `$cache` - (required) parent SessionCache object
    `$id` - (optional) unique identifier for the session; default is generated from an internal integer generator
    `$timeout` - (optional) max inactivity timeout; default is 10 minutes
    `$dough` - (optional) any information to be included in the session cookie; the $id will be prepended to this information
    `$expires` - (optional) RFC1123 formatted cookie expiration date string, or 'Never'; default is single session (nonpersistent)
  Returns:
    HTTP::Response object

Method Details

### close

    close()

  Closes this session and removes it from the parent SessionCache. May cause any underlying persistent session store to delete its version of the session.

  Returns:
    undef (to optimize clearing any containers)

### cookieSent

    cookieSent()

  Called to indicate that the cookie has been sent to the client.

  Note: Subclasses which implement `open()` should already set this flag when a session is successfully recovered.

  Returns:
    this Session object

### getAttribute

    getAttribute($name)

  Returns the object bound with the specified name.

  Parameters:
    `$name` - name of attribute to retrieve
  Returns:
    the value of the named attribute (if any)

### getAttributeNames

    getAttributeNames()

  Returns the list of attributes bound to this session.

  Returns:
    (the alphabetically sorted list of attribute names )

### getCookie

    getCookie()

  Returns this session's cookie

  Returns:
    the cookie string, including the unique session ID, and any dough and/or expiration date supplied when the session was created

### getCreationTime

    getCreationTime()

  Returns the creation time of this session as a fractional number.

  NOTE: As a read operation on a static value, no lock is required.

  Returns:
    the creation time of the session as a floating point number of seconds since the epoch.

### getExpiration

    getExpiration()

  Get expiration on this session.

  Returns:
    the RFC1123 formatted expiration (if any)

### getID

    getID()

  Returns the unique ID time of this session

  NOTE: As a read operation on a static value, no lock is required.

  Returns:
    the ID string

### getLastAccessedTime

    getLastAccessedTime()

  Returns the last time the client sent a request for this session.

  Returns:
    the time as a floating point number of seconds sinc the epoch

### getMaxInactiveInterval

    getMaxInactiveInterval()

  Returns the last time the client sent a request for this session.

  Returns:
    the time as a floating point number of seconds sinc the epoch

### isInactive

    isInactive()

  Has this session timed out ?

  Returns:
    boolean true if the inactivity timeout has expired; else false

### isNew

    isNew()

  Returns true if the cookie for the session has not yet been sent to the client. Note that this session instance may have been revivified from persistent storage, and has not yet sent its cookie to the client, but the client has previously stored the cookie, in which case this method should return false.

  Returns:
    1 if the cookie has not been sent, undef otherwise

### removeAttribute

    removeAttribute($name)

  Removes the object bound to the specified name from this session.

  Parameters:
    `$name` - name of attribute to remove
  Returns:
    the value of the removed attribute

### setAttribute

    setAttribute($name, $value)

  Set an attribute on this session, using the name specified.

  NOTE: Since Session objects are threads shared, their attributes hash is also threads::shared, which means that any non-scalar values to be assigned to an attribute must also be threads::shared.

  Parameters:
    `$name` - name of attribute to set
    `$value` - value of the attribute to set
  Returns:
    the Session object

### setExpiration

    setExpiration($expires)

  Set expiration on this session. If no date is given, then the cookie is expired.

  Parameters:
    `$expires` - RFC1123 expiration timestamp
  Returns:
    the Session object

### setLastAccessedTime

    setLastAccessedTime()

  Set the last time the client sent a request for this session.

  Returns:
    this Session object

### setMaxInactiveInterval

    setMaxInactiveInterval($timeout)

  Set the max inactivity interval, in seconds, for this session.

  Parameters:
    `$timeout` - inactivity interval in seconds
  Returns:
    this Session object

Generated by psichedoc on Mon Aug 28 09:45:39 2006