[Zope-CVS] CVS: Products/Sessions/help - Sessions.stx:1.1

[Matthew T. Kromer]

Update of /cvs-repository/Products/Sessions/help
In directory cvs.zope.org:/tmp/cvs-serv2132/help

Added Files:
	Sessions.stx 
Log Message:
Get Sessions working


=== Added File Products/Sessions/help/Sessions.stx === (1189/1289 lines abridged)
Core Session Tracking Release 0.9 Documentation

  This is the documentation to the Core Session Tracking product.
  Session tracking allows you to keep state between HTTP requests for
  anonymous users.

  The Big Picture

    There are four major components to the CoreSessionTracking design:

      - Session Id Manager -- this is the component which determines a
        remote client's session id.  The session id is contained in the
        "session token", which is encoded in a form or cookie variable.
        The session id manager examines and modifies cookie and
        form variables to determine or set the client's session id.
        There may be more than one session id manager in a Zope
        installation, but commonly there will only be one.  Application
        developers will generally not talk directly to a session id
        manager.  Instead, they will talk to session data managers,
        which will delegate some calls to a session id manager.  Session
        id managers have "fixed" Zope ids so they can be found via
        acquisition by session data managers.

      - Session Data Manager -- this is the component which is
        responsible for handing out session data to callers.  When
        session data is required, the session data manager talks to a
        session id manager to determine the current session token and
        creates a new session data object or hands back an existing
        session data object based on the token.  It also has interfaces
        for encoding a URL with session information and performing other
        utility functions.  Developers will generally use methods of
        session data managers to obtain session data objects when
        writing application code.  Many session data managers can use
        one session id manager.  Many session data managers can be
        instantiated on a single Zope installation.  Different session
        data managers can implement different policies related to
        session data object storage (e.g. to which session data
        container the session data objects are stored).

      - Session Data Container -- this is the component which actually
        holds information related to sessions.  Currently, it is used to
        hold a special "session data object" instance for each ongoing
        session.  Developers will generally not interact with session
        data containers.  The current implementation defines two types
        of session data containers: internal and external.  "Internal"
        session data containers are RAM-based, and they are available
        for use on a per-session-data-manager basis, while "external"
        session data containers are persistent Zope objects which may be
        used to store (and persist) session data objects. External
        session data containers are traversable, and they are meant to

[-=- -=- -=- 1189 lines omitted -=- -=- -=-]

      log (or they may be printed to the console from which you run
      Zope).  An example of one of these errors is as follows::

       2001-01-16T04:26:58 INFO(0) Z2 CONFLICT Competing writes at, /getData
       Traceback (innermost last):
       File /zope/lib/python/ZPublisher/Publish.py, line 175, in publish
       File /zope/lib/python/Zope/__init__.py, line 235, in commit
       File /zope/lib/python/ZODB/Transaction.py, line 251, in commit
       File /zope/lib/python/ZODB/Connection.py, line 268, in commit
       ConflictError: '\000\000\000\000\000\000\002/'

      Errors like this in your debug log (or console if you've not
      redirected debug logging to a file) are normal to an extent.  If
      your site is undergoing heavy load, you can expect to see a
      ConflictError perhaps every 20 to 30 seconds.  The requests
      which experience conflict errors will be retried automatically
      by Zope, and the end user should *never* see one.  Generally,
      session data objects attempt to provide application-level
      conflict resolution to reduce the limitations imposed by
      conflict errors NOTE: to take advantage of this feature, you
      must be running Zope 2.3.1 or better, and you must be using it
      with a storage such as FileStorage or SessionStorage which
      supports application-level conflict resolution.

  Zope Versions and Sessioning

      Zope Versions are not particularly useful in combination with
      sessioning.  Particularly, if you change the properties of a
      session data manager or session id manager while working in a
      Version on a "production" site, it may cause the sessioning
      machinery to stop working for unversioned visitors to the site
      due to the "locking" nature of versions.  To work around this
      problem, do not lock any sessioning-related objects while in a
      Version.  Alternately, do not use Versions.

  Extending The Session Tracking Product

    Implementing Alternate Session Data Managers and Data Containers

      Alternate session data managers and data containers (perhaps
      using a SQL database as a persistence mechanism) may be
      implemented if they adhere to the interfaces outlined in the
      SessioningInterfaces.py documentation which ships with this
      software.

  Bug Reports and Feature Requests

    Please use the CoreSessionTracking Discussion Wiki page at
    http://dev.zope.org/Wikis/DevSite/Projects/CoreSessionTracking/FrontPage
    or send email to zope@zope.org (the Zope general mail list).