Agent.Request

Agent.Request: Execution Context and Support APIs

• Agent.Request ($req) is similar to Apache/mod_perl's "r" structure. $req holds the context for the collection of operations for a shell command, background job in the server, or an HTTP request via mod_perl.

• The context contains well-known attributes as well as arbitrary state provided by the business logic. Essentially, it is a collection of global variables which only remain active for the duration of a "request".

• Key attributes:

  • auth_realm, auth_id - the realm in which the current operation is executing. Can be changed with set_realm.

  • auth_user, auth_user_id - the RealmOwner instance for the currently authenticated user. set_user changes the auth_user.

  • auth_roles - the roles the auth_user has in auth_realm

  • task, task_id - the currently executing task (even a ShellUtil has a task, which typically is the SHELL_UTIL task)

  • uri, query, path_info - corresponding to HTTP/CGI objects

  • form, content - data associated with the request

  • user_state - visitor, logged in user, logged out

  • timezone - user's timezone

  • can_secure, is_secure, is_production - booleans controlling workflow

  • Model. - a model instance which has been loaded or processed (executed)

  • UI.Facade - the Facade associated with the request (usually controlled by incoming domain name, but can be set explicitly).

  • txn_resources - queue of objects which have registered interest in the current transaction. Typical transaction resources are instances of SQL.Connection, Mail.Outgoing, Model.Lock, and Model.RealmFile. Although any object can participate in the transaction.

• Transactions: The request holds the state of the transaction (txn_resources). When a Task finishes executing, the Dispatcher will call $req->commit or $req->rollback depending on the result/exception causing the Task to terminate. There are only a few places where rollback or commit is called.

• URI writing: format_uri, format_http, format_email, etc. are found in Agent.Request for convenience but most of the formatting occurs elsewhere. The request holds much of the state that is used in the default values for these calls.

• Client and server redirects: Agent.Request manages requests to switch to a new task via the client or internally within the server. A call to client_redirect or server_redirect accepts similar parameters to format_uri. In the case of client_redirect, the result is a URI created by format_uri.