/ 
OpenInteract-1.62
River stage zero No dependents
/ OpenInteract::Request

NAME

OpenInteract::Request -- container for request info and output

SYNOPSIS

# Anywhere in your website

my $R = OpenInteract::Request->instance;
my $user_rec = $R->user->fetch( $user_id );
my $org_recs = $R->org->fetch_group;

my $db_info = $R->CONFIG->db_info();
my $dbh  = $R->db;

DESCRIPTION

The Request object is fairly simple, having only a few methods to it. But it really ties applications together in the OpenInteract framework, acting as an object repository, a layer between your object names and their classes, and as a data store between different parts of the process. Since it is 'always around' (more later), you can thus have necessary configuration information, your database handle, cache store, template parser or other tools at your fingertips.

This package is designed to run under mod_perl. Since it is a subclass of Class::Singleton, it maintains the request object (usually $R) around for the life of the Apache child. The intended side effect of this allows you to pluck the object from the ether from any handler or utility you are running by simply doing:

my $R = OpenInteract::Request->intance;

That is it. You do not need a 'use OpenInteract::Request;' statement, you do not need to pass the object around from method to method.

The other job of the OpenInteract::Request object is to keep track of where we are: which action we are using, what URL was originally requested. etc.

PACKAGE LEXICALS

%OBJECTS

Hash holding all the general objects needed throughout this request. Note that finish_request() cleans these up (except for the database handle and config object) at the end of every request.

%ALIAS

Holds mapping of alias to class name. When the website is first started, you should call:

OpenInteract::Request->setup_aliases();

Which turns these hash entries into subroutines so you can use the inline method -- $R->user vs $R->user(). The latter one is necessary if you do everything strictly via AUTOLOAD. (Been there, done that...)

METHODS

instance()

Returns: a blessed Request object. (Inherited from Class::Singleton.)

initialize()

Initialize the request. You can override this however you wish.

throw( \%params )

Make it easy to throw errors from anywhere in the system. All information gets passed directly to OpenInteract::Error, although we set the package, filename and line information so it does not appear to the error handler that all errors are mysteriously being thrown from OpenInteract::Request, and all from one line, too... :)

Note that you do not even need to instantiate an object for this:

OpenInteract::Request->instance->throw( { ... } );

See also documentation in OpenInteract::Error and the OpenInteract::ErrorObject, particularly for the parameter names.

stash( 'name', $obj )

Adds an object indexed by 'name' to our stash class. If the object already exists in the stash class, the default behavior is to simply overwrite. (You can write a more complicated stash class if you like...)

Examples:

$R->stash( 'db', $db );
$R->stash( 'apache', $apr );

get_stash( 'name' )

Retrieves the value corresponding to 'name' from the current stash class. Note that many aliases (e.g., "$R->db") actually call 'get_stash' internally, so you will not see this used very frequently.

db_stash( $handle, [ $connection_key ] )

ldap_stash( $handle, [ $connection_key ] )

setup_aliases()

Creates subroutines in the symbol table for this class matching up to the entries in the lexical %ALIAS. You should call this when your website first starts.

lookup_alias( $alias )

Returns a class name matching up to $alias. Use this when you do not know the alias beforehand. You can use it in two different ways:

1)  $R->$alias()->fetch( $id );

2)  my $class = $R->lookup_alias( $alias );
    my $obj = $class->fetch( $id );

scrib( $level, $msg [, $msg, $msg, ... ] )

Centralized notification logging. Check the {DEBUG} key in the config object, which is stored in the stash class, for the current debugging level. If that level is less than the level passed in, we do nothing. But if the value is equal to or greater than the level passed in then we 'warn' with the error.

A common idiom is:

$R->DEBUG && $R->DEBUG && $R->scrib( 1, "Result:", $myobj->result() );

This first checks to see if debugging is on, and if so only then calls the (more expensive) scrib() method. As seen below, DEBUG() checks the application debugging level (generally from the server configuration), so this might send debugging info for one website but not another.

Note that you can pass multiple messages at once to the method -- the method joins them with a single space between the messages.

None of the $msg items need to conetain the filename, package name, subroutine name or line number -- we pull all that from the reference material sent via caller.

You can use this as a class method as well:

OpenInteract::Request->instance->scrib( 2, "Boring log message" );

And you can use either the object or class methods even if you have not created and registered a config object. If you have not done so, we will use the value of the package variable $DEBUG in this class.

This means that setting the value of the package variable $DEBUG will send all messages from any application at that level or lower to 'warn'. Be careful or you will get some big honking logfiles! You might want to use local for setting this value if you really need to.

Finally, any log messages sent with a debug level of '0' will always go to the log, as long as you do not check the result of DEBUG() first.. (We have not accounted for any weisenheimers setting the config/class debug level to a negative number, but who would do such a thing?)

DEBUG()

Class or object method to return the current debugging level. If this is called from an object, we query the configuration hashref in the stash class for the debugging level and return it. If that is not set, we also check the class variable 'DEBUG' and send its value. Most of the time you will not want to set this because you will get enormous logfiles. But hey, if that is what you want...

lookup_conductor( [ $action ] )

Finds the conductor for a particular action.

Returns a two-element list: class and method.

If $action is not passed in, we find the name from $R->{path}->{current}.

lookup_action( [ $action, \%params ] )

Finds information associated with a particular action from the configuration.

If $action is not passed in, we find the name from $R->{path}->{current}.

You have the option of refusing to allow the method to return a default action if yours is not found. We use this to implement 'static' web pages. For instance, if there is no action corresponding to the path '/mod_perl/guide/toc', then we find the default action (which handles page objects) and return its information.

Returns either a two-element list (class and method) or with a 'return' parameter value of 'info', returns a hashref with all known information about the action.

Parameters:

  • return ($)

    'info' means return all information about the action

  • skip_default (bool)

    Any true value means to *not* use the default action name, even if the action name is not found.

finish_request()

Cleans out this object and tells the stash class associated with the request to do the same.

TO DO

Nothing known.

BUGS

none known.

COPYRIGHT

Copyright (c) 2001-2002 intes.net, inc.. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

Christian Lemburg <lemburg@aixonix.de> bugged me about getting a logging method (scrib) in here.