NAME
    MasonX::Request::WithMulti2Session - Multiple sub-sessions within one
    "parent" session

SYNOPSIS
      PerlSetVar  MasonRequestClass  MasonX::Request::WithMulti2Session

DESCRIPTION
    MasonX::Request::WithMulti2Session is experimental ( beta ) and should
    only be used in a test environment.

    MasonX::Request::WithMulti2Session is a clone of
    MasonX::Request::WithMultiSession changed to work under a pure mod_perl2
    environment. The external interface is unchanged, see
    MasonX::Request::WithMultiSession.

    The actual changes I made can be found in the distribution in
    diff/WithMultiSession.diff ( made with 'diff -Naru' ... ).

    A HOWTO for MasonX::Apache2Handler and friends may be found at
    Mason-with-mod_perl2.

    The following documentation is from MasonX::Request::WithMultiSession.

    This module subclasses "MasonX::Request::WithApache2Session" in order to
    allow multiple "sub-sessions" to exist within one parent session.

    This can be quite useful for a web app where you want to allow the user
    to open multiple windows, each with a different session, but session ids
    are stored in a cookie.

    Like "MasonX::Request::WithApache2Session", sub-sessions are shared
    between a request and any subrequests it creates.

METHODS
    This class has an interface quite similar to that of
    "MasonX::Request::WithApache2Session".

    * session
        The primary interface to this class is through the "session()"
        method. When this method is called without any parameters, the
        module looks for an existing sub-session specified by the
        sub-session id argument parameter (which can be in a query string or
        POST). This value can be overridden by explicitly passing a
        "sub_session_id" parameter.

        If this parameter is found, an existing sub-session is returned. If
        this parameter is not found, a new sub-session is created.

        If the "session()" method is called as "session( clone => 1 )" then
        a new sub-session will be created, and its contents will be the same
        as that of the current sub-session. This is a shallow copy of the
        old session hash, so objects and references are shared between them.

        If "session( new => 1 )" is called, then a new, empty, sub-session
        is created.

        You can specify the main session id to use via the "session_id"
        parameter.

    * sub_session_id
        This method returns the currently active sub-session's id. Use this
        method to put this id into URL parameters, forms, etc. as needed.

        If given a "sub_session_id" parameter, it will set the current
        sub-session id.

    * delete_sub_session
        By default, this simply defaults the current sub-session. You can
        pass a "sub_session_id" parameter to delete a specific session.

  Parameters
    This module takes two parameters besides those inherited from
    "MasonX::Request::WithApache2Session":

    * multi_session_args_param / MultiSessionArgsParam
        This parameter can be used to specify which parameter contains the
        sub-session id. By default, the module will look for a parameter
        called "sub_session_id".

    * multi_session_expire / MultiSessionExpire
        This parameter specifies the number of seconds after a sub-session
        is accessed until it is purged. If not specified, then sub-sessions
        are never purged.

        Sub-sessions expiration is checked when the request object goes out
        of scope.

USAGE
    You will need to manually set the sub-session id argument parameter for
    each request. The easiest way to do this is to make sure that all URLs
    contain the sub-session id. This can be done by using a "<%filter>"
    block in a top-level autohandler (although this won't catch redirects),
    or by making sure all URLs are generated by a single component/function.

SUPPORT
    Bug reports and requests for help should be sent <mason@beaucox.com>.

AUTHOR
    Beau E. Cox <mason@beaucox.com> <http://beaucox.com>.

    The real authors (I just made mod_perl2 changes) is Dave Rolsky,
    <autarch@urth.org>

    Version 0.01 as of January, 2004.

SEE ALSO
    My documents, including: HOWTO Run Mason with mod_perl2,
    MasonX::Apache2Handler, MasonX::Request::WithApache2Session.

    Original Mason documents, including: HTML::Mason::ApacheHandler,
    MasonX::Request::WithApacheSession, MasonX::Request::WithMultiSession.

    Also see the Mason documentation at <http://masonhq.com/docs/manual/>.