   # ... official way to get a Context object ...
   use P5EEx::Blue::P5EE;
   $context = P5EEx::Blue::P5EE->context();
   $config = $context->config();   # get the configuration
   $config->dispatch_events();     # dispatch events

   # ... alternative way (used internally) ...
   use P5EEx::Blue::Context::CGI;
   $context = P5EEx::Blue::Context::CGI->new();

DESCRIPTION

A Context class models the environment (aka ``context) in which the current process is running. For the P5EEx::Blue::Context::CGI class, this models the CGI environment.

The role of the Context::CGI class is to abstract the details of the CGI runtime environments (including the ``event loop'', which spans multiple HTTP requests).

The Context object is a singleton per process.

Protected Methods:

The following methods are intended to be called by subclasses of the current class.

`init()`

The init() method is called from within the standard Context constructor.

The CGI Context implements the init() method to take into account that a CGI object might have been passed in as an argument. If a CGI object is not passed in as an argument, a new CGI object is created, thus parsing the CGI request.

    * Signature: $context->init($args)
    * Param:     $args            hash{string} [in]
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01

    Sample Usage:

    $context->init($args);

Public Methods:

`log()`

This method is inherited from P5EEx::Blue::Context.

`user()`

The user() method returns the username of the authenticated user. The special name, ``guest'', refers to the unauthenticated (anonymous) user.

    * Signature: $username = $context->user();
    * Param:  void
    * Return: string
    * Throws: <none>
    * Since:  0.01

    Sample Usage:

    $username = $context->user();

`config()`

This method is inherited from P5EEx::Blue::Context.

Public Methods: Debugging

`dbg()`

This method is inherited from P5EEx::Blue::Context.

`dbgprint()`

This method is inherited from P5EEx::Blue::Context.

`dbglevel()`

This method is inherited from P5EEx::Blue::Context.

`dbgscope()`

This method is inherited from P5EEx::Blue::Context.

Protected Methods

These methods are considered protected because no class is ever supposed to call them. They may however be called by the context-specific drivers.

`dispatch_events()`

The dispatch_events() method is called by the CGI script in order to get the Context object rolling. It causes the program to process the CGI request, interpret and dispatch encoded events in the request and exit.

In concept, the dispatch_events() method would not return until all events for a Session were dispatched. However, the reality of the CGI context is that events associated with a Session occur in many different processes over different CGI requests. Therefore, the CGI Context implements the dispatch_events() method to return after processing all of the events of a single request, assuming that it will be called again when the next CGI request is received.

    * Signature: $context->dispatch_events()
    * Param:     void
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01

    Sample Usage:

    $context->dispatch_events();

`dispatch_request_events()`

The dispatch_request_events() method executes the events within a single CGI request. It has no display functionality.

It is called primarily from the event loop handler, dispatch_events(). However, it may be called from external software if that code manages the event loop itself. i.e. it instantiates the CGI object outside of the Context and passes it in, never calling dispatch_events(). Instead, it would call dispatch_request_events().

    * Signature: $context->dispatch_request_events()
    * Signature: $context->dispatch_request_events($cgi)
    * Param:     $cgi            (CGI)
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01

    Sample Usage:

    $context->dispatch_request_events();