The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_06
River stage zero No dependents
1 ++
/ OpenInteract2::Request

NAME

OpenInteract2::Request - Represent a single request

SYNOPSIS

 # In server startup/OI::Context initialization
  
 OpenInteract2::Request->set_implementation_type( 'cgi' );
 
 # Later...
 
 my $req = CTX->request;
 print "All parameters: ", join( ', ', $req->param(), "\n";
 print "User agent: ", $req->user_agent(), "\n";

DESCRIPTION

This object represents all information that we know about a request. It is modeled after the interfaces for CGI and Apache::Request, so there are a couple of items that are slightly inconsistent with the rest of OpenInteract.

When you create a new request object you need to specify what type of request it is. (Your OpenInteract server configuration should have this specified in the 'context_info' section.) The process of initializing the object during the new() call fills the Request object with any parameters, uploaded files and important headers from the client.

The OpenInteract2::Context object is responsible for associating cookies and the session with this request object.

METHODS

Class Methods

set_implementation_type( $type )

get_implementation_type()

new( @params )

Parameters

param( [ $name, $value ] )

See docs in OpenInteract2::ParamContainer

param_url_additional()

Property that returns as a list any additional path information as parameters. This allows REST-style URLs.

What constitutes 'additional' is determined by the relevant OpenInteract2::ActionResolver class -- the one that's able to resolve a URL into an OpenInteract2::Action object is also responsible for setting this property.

For instance, instead of:

  http://www.foo.com/news/display/?news_id=1

You could have:

 http://www.foo.com/news/display/1

And instead of:

 http://www.foo.com/news/archive/?year=2005&month=8

You could use:

 http://www.foo.com/news/archive/2005/8

Returns: list of additional parameters, in order.

param_toggled( $name )

Given the name of a parameter, return 'yes' if it is defined and 'no' if not.

param_boolean( $name )

Given the name of a parameter, return 'TRUE' if it is defined and 'FALSE' if not. (This maps to the SQL standard for boolean literals.)

param_date( $name, [ $strptime_format ] )

Given the name of a parameter return a DateTime object populated with the data input from the HTTP request.

The parameter $name can refer to:

  1. a single field, in which case you must specify a strptime format in $format

  2. multiple fields where $name is a prefix and '_year', '_month', '_day' are the suffixes.

For example:

 # mydate = '2003-04-01'
 my $datetime = $request->param_date( 'mydate', '%Y-%m-%d' );
 
 # mydate_year  = '2003'
 # mydate_month = '04'
 # mydate_day   = '01'
 my $datetime = $request->param_date( 'mydate' );

If you specify a format and the parser cannot parse the date you give with that format an exception will be thrown.

param_datetime( $name, [ $format ] )

Similar to param_date in that it reads parameter information and returns a DateTime object, except it also reads hour, minute and AM/PM information.

The parameter $name can refer to:

  1. a single field, in which case you must specify a strptime format in $format

  2. multiple fields where $name is a prefix and '_year', '_month', '_day', '_hour', '_minute' and '_am_pm' are the suffixes.

For example:

 # mytime = '2003-04-01 6:08 PM'
 my $datetime = $request->param_date( 'mytime', '%Y-%m-%d %I:%M %p' );
 
 # mytime_year   = '2003'
 # mytime_month  = '04'
 # mytime_day    = '01'
 # mytime_hour   = '6'
 # mytime_minute = '08'
 # mytime_am_pm  = 'PM'
 my $datetime = $request->param_datetime( 'mytime' );

If you specify a format and the parser cannot parse the date you give with that format an exception will be thrown.

Request URL

assign_request_url( $full_url_path )

This method is normally only called by the implementing subclass. The subclass should pass the full, absolute URL path -- no protocol, host or port, but query arguments should be included. With this the url_absolute and url_relative properties are properly set. The method also sets the action name and task for use by the controller, delegating the actual work to OpenInteract2::URL.

If you want to do any behind-the-scenes redirection before the OpenInteract2::Controller is instantiated, you can pass a path to this and the correct action will be processed. For instance, you can configure your site to force users to login so no matter what URL is requested by a user who is not logged in they will always get your login page. This is done in the OpenInteract2::Auth class -- if the user is not logged in it assigns a new request URL which changes the action processed by the controller.

Incoming Cookies

cookie( [ $name, $value ] )

With no arguments it returns a list -- not an arrayref! -- of cookie names the client passed in.

If you pass in $name by itself you get the value associated with the cookie. This is a simple scalar value associated with the name, not a CGI::Cookie object.

If you pass in a $value along with $name then it is assigned to $name, overwriting whatever may have been there before.

Note: These are only incoming cookies, those the client sends to the server. For outgoing cookies (setting cookies on the client from the server) see OpenInteract2::Response.

Returns: list of cookie names (no argument), the value associated with the first argument (one argument, two arguments).

Incoming Uploads

upload( [ $name ] )

With no arguments, this returns a list -- not an arrayref! -- of OpenInteract2::Request::Upload objects mapping to the files uploaded by the client. If you pass in $name then you get the specific OpenInteract2::Request::Upload object associated with it.

Returns: list of parameters (no argument), or the parameter associated with the single argument.

clean_uploads()

Deletes all uploads associated with the request.

Language/Localization

language() (read-only)

Returns the language(s) chosen for this particular request. This is one of the few context-sensitive properties. If called in list context it will return a list of all languages supported in this request, even if only one is available. If called in scalar context it will return the first (and presumably most important) language.

See OpenInteract2::Manual::I18N for how we find the language(s) desired for this request.

language_handle() (read-only)

A Locale::Maketext object from which you can get localized messages.

assign_languages( [ @assigned ] )

Typically called only by an adapter or the authentication classes which use the default behavior described below. But you can also assign languages directly to the request object with this:

 $request->assign_languages( 'en', 'jp', 'sv' );

If you do assign languages directly any language handle previously cached for the request is removed.

Otherwise we find the language from one of:

  • the user (if logged in)

  • session (from 'language' key);

  • parameter value (listed in server configuration of 'language.choice_param_name';

  • or default language set in 'language.default_language'.

Properties

url_absolute

This is set to the URL the user entered, still containing the deployment context.

url_relative

This is set to the internal URL OI uses. It does not include the deployment context. It should be the URL all actions deal with.

url_initial

This is the URL we used to lookup the action.

theme

Theme object associated with this request. May change if user is logged in and has different theme.

theme_values (read-only)

Hashref (not an object) of flattened theme properties. This is set automatically when theme property is set.

session

The stateful session for the current user.

action_name

Name of the action as gleaned from the URL. (May be empty, may change as a result of lookups.)

task_name

Task of the action as gleaned from the URL. (May be empty, may change as a result of lookups.)

auth_user

User logged in (or not) for this request. This should always be filled with a user object, even if it is the 'not-logged-in' user.

auth_group

Groups current user belongs to. May be empty.

auth_is_admin

True if current user is an administrator, false if not. (You can customize this: see OpenInteract2::Auth::AdminCheck).

auth_is_logged_in

True if current user is a legitimate user, false if it is the 'not-logged-in' user.

auth_user_id

Shortcut so you do not have to test whether the user is logged in to get an ID. If the user is not logged in, you get a '0' back.

auth_clear

Clears out all the 'auth_*' properties to undef -- generally only used when you want to log a user out for the current request.

server_name

Hostname of our server.

remote_host

Client IP address or hostname connecting to us.

user_agent

The browser identification string. (May be empty, forged, etc.)

referer

URL (string) where the user came from. (May be empty, forged, etc.)

Action Messages

Actions or other code can leave messages for other actions. These messages are typically tagged errors so the action and/or view knows how to sort through them, but it is not required. For instance, if a login fails we want to be able to indicate this so that the login box can display the right type of error message. Normally you would set the messages directly in the action (via add_view_message()), but in the (fairly rare) case where the two are disconnected you can deposit error messages in the request and the relevant action will know where to pick them up when it is later instantiated.

action_messages( $action_name, [ \%messages ] )

Retrieve hashref of messages for action $action_name, case-insensitive. Overwrite all existing messages with \%messages if it is provided.

Returns: hashref of action messages for action $action_name; empty hashref if $action_name not provided.

add_action_message( $action_name, $msg_name, $msg )

Adds an individual message $msg_name with message $msg to $action_name. The $msg_name may be whatever you like, but frequently it is an object field name.

Returns: $msg set

SUBCLASSING

If you're extending OpenInteract to a new architecture and need to create a request adapter it is probably best to look at an existing one to see what it does. (Working code is always more up-to-date than documentation...) That said, here are a few tips:

  • If your architecture is deployed under a particular URL you should set this as soon as possible. Do so using the assign_deploy_url() method of the context. See OpenInteract2::Request::CGI for an example.

Other than that take a look at OpenInteract::Request::Standalone. It forces you to deal with parameters and file uploads yourself, but it may be the path of least resistance.

Methods

_set_upload( $name, $upload )

Associates the OpenInteract2::Request::Upload $upload object with $name.

Returns: the upload object

Parent initialization

The following methods are available for subclasses -- the idea is they get the relevant data in a platform-dependent manner (parsing a header, reading an envionment variable, whatever) and pass it to this class to parse the data and place them in the right structure.

_parse_cookies()

Reads the cookie_header property and parses it into the name/value pairs returned from the cookie() method. So your adapter must set this header to have the cookies created and/or create the cookies yourself using cookie(). (OpenInteract2::Request::Standalone is an example of doing both)

_create_session()

Reads in the cookie with the name defined in the constant SESSION_COOKIE from OpenInteract2::Constants and uses its value as the session ID passed to OpenInteract2::SessionManager to create the session, which is stored in the session property.

SEE ALSO

Class::Factory

OpenInteract2::Request::Apache

OpenInteract2::Request::Apache2

OpenInteract2::Request::CGI

OpenInteract2::Request::LWP

OpenInteract2::Request::Standalone

COPYRIGHT

Copyright (c) 2002-2005 Chris Winters. 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>