Para::Frame::Request - The request from the client
Para::Frame::Request is the central class for most operations. The
current request object can be reached as $Para::Frame::REQ.
Para::Frame::Request->get_by_id( $id )
$req->get_by_id( $id )
Looks for the id in the subrequests of the req, recursive.
$req->new_subrequest( \%args, \&code, @params )
Sets up a subrequest using /new_minimal.
&code (in scalar context) with the req as the first param, followed by @params
args:
site: A L<Para::Frame::Site> object. If defined, and the host differs from that of the current request, we sets ut a background request that can be used to query apache about uri2file translations. user: A L<Para::Frame::User> object. Defaults to the current user.
A subrequest must make sure that it finishes BEFORE the parent, unless it is decoupled to become a background request.
The parent will be made to wait for the subrequest result. But if the subrequest sets up additional jobs, you have to take care of either makeing it a background request or making the parent wait.
We creates the new request with /new_minimal and sends the
\%args to /minimal_init.
Sets up a background request using new_minimal
Initializes the /http_init request for http requests
Used for background jobs, without a calling browser client
$req->minimal_init( \%args )
Initializes the /new_minimal request. A smaller version of init.
args:
site: The site for the request, set by L</set_site>. Optional. language: The language for the request, set by L</set_language>, that will use a default if no input. user: The L<Para::Frame::User> to be in this request. Defaults to using L<Para::Frame/bg_user_code> for getting the user.
Returns: The request
$req->id
Returns the request number
$req->q
Returns the CGI object.
TODO: Replace CGI module with URI::QueryParam
$req->session
Returns the Para::Frame::Session object.
$req->env
Returns a hashref of the environment variables passed given by Apache for the request.
$req->client
Returns the object representing the connection to the client that made this request. The stringification of this object is used as a key in several places.
$req->cookies
Returns the Para::Frame::Cookies object for this request.
$req->result
Returns the Para::Frame::Result object for this request.
$req->result_message( $message )
Sends a message to the result, or just the log if no result object.
$req->language
Returns the L10N language handler object.
$req->set_language() $req->set_language( $language_in )
This is called during the initiation of the request.
Calls Para::Frame::L10N/set or a subclass theriof defined in Para::Frame/l10n_class.
$req->response
Returns the Para::Frame::Request::Response object.
$req->page
Returns a Para::Frame::File object from Para::Frame::Request::Response/page.
$req->original
If this is a subrequest; return the original request.
$req->equals( $req2 )
Returns true if the two requests are the same.
$req->user
Returns the Para::Frame::User object. Or probably a object of a subclass of that class.
This is short for calling $req->session->user
Returns undef if the request doesn't have a session.
$req->require_root_access
Throws a denied exception if the current user hasn't root access
$req->change
Returns the Para::Frame::Change object for this request.
$req->is_from_client
Returns true if this request is from a client and not a background server job or something else. Not true for direct http_requests, as those are meant for ajax/json.
$req->dirconfig
Returns the dirconfig hashref. See Apache/SERVER CONFIGURATION
INFORMATION dir_config.
Params:
site: Used by Para::Frame::Request/reset_response. If
site is set to ignore, the Para::Frame::Client will decline
all requests and let thenext apache handler take care of it.
action: Used by /setup_jobs
port: Used by Para::Frame::Client
backup_port: Used by Para::Frame::Client
backup_redirect: Used by Para::Frame::Client
backup: Used by Para::Frame::Client
find: Used by Para::Frame::File/template
loadpage: Used by Para::Frame/handle_request. If loadpage is
set to no, a loadpage will not be sent.
do_forward: Used by Para::Frame::Request::Response/send_output.
If do_forward is set to no, we will not redirect, even on errors.
Example for a .htaccess PerlSetVar site ignore
$req->browser
Returns the HTTP::BrowserDetect object for the request.
$req->uploaded( $filefiled )
Calls Para::Frame::Uploaded/new
$req->in_yield
Returns true if this request has yielded for another request, or for reading from the socket
$req->uri2file( $url ) $req->uri2file( $url, $file ) $req->uri2file( $url, undef, $return_partial )
This does the Apache URL to filename translation
Directory URLs must end in '/'. The URL '' is not valid.
The answer is cached. Remove an url from the cache with uri2file_clear.
If given a $file uses that as a translation and caches is.
(This method may have to create a pseudoclient connection to get the information.)
If $return_partial is true, we will return a part of the path
instead of throwing an exception.
Returns:
The file WITH '/' for dirs (NB! CHANGED)
Exceptions:
Throws a notfound exception if translation results in a file where the last part differs from the one sent in. That would be the case when the directory doesn't exist or for unsupported url translations.
$req->uri2file( $url ) $req->uri2file()
Clears the $url from the cache for the $req host.
With no $url, clear all uris from the cache.
$req->normalized_url( $url ) $req->normalized_url( $url, $params )
Gives the proper version of the URL. Ending index.tt will be removed. This is used for redirecting (forward) the browser if nesessary.
$url must be the path part as a string.
params:
no_check
Returns:
the path part as a string
$req->setup_jobs()
Set up things from params.
$req->add_job($method, @args)
This will run $req-<$method(@args) when the job is processed.
For a custom job, use /run_code.
Remember du add the job /after_jobs if this is the last job.
$req->add_background_job( $label, \&code, @params )
Runs the &code in the background with the given @params.
$label is used for keeping metadata about what jobs are in queue.
Background jobs are done in between regular requests.
The $req is given as the first param.
Example:
my $idle_job = sub
{
my( $req, $thing ) = @_;
debug "I'm idling now like a $thing...";
};
$req->add_background_job( 'ideling', $idle_job, 'Kangaroo' );
$req->prepend_background_job( $label, \&code, @params )
May still take a lot of time since the prepended background job is then appended to the list of current jobs.
$req->run_code( $label, $coderef, @args )
This will run &{$coderef}($req, @args).
Usually set up by
$req->add_job('run_code', $label, $coderef, @args);
See /add_job.
If the action requires the user to login, a new
Para::Frame::Request::Response will be created for the /login.tt
template.
If the session object can Para::Frame::Session/go_login and the
method returns true, it will be used instead of a redirection to
/login.tt template.
$req->referer_path
Returns the LOCAL referer. Just the path part. If the referer was from another website, fall back to default.
(This gives the previous caller page)
Returns the URL path part as a string.
$req->referer_query
Returns the escaped form of the query string. Should give the same result regardless of GET or POST was used.
Defaults to ''.
$req->referer_with_query
Returns referer with query string as a string.
This combines /referer and /referer_query.
$req->may_yield $req->may_yield( $wait )
Calls /yield only if there was more than 2 seconds since the last yield.
For operations taking a lot of time, insert this in places there a change of request is safe.
$req->yield $req->yield( $wait )
This calls the main loop, changing all global variables if another request is processed. Then that request is done, we return. If there was nothing to do, we will come back here quickly.
If $wait is given, waits a maximum of that amount of time for
another request. Mostly to be used if we know that another request is
coming and we want that to be handled before we continue.
$req->http_host
Returns the host name the client requested. It tells with which of the alternatives names the site was requested. This string does not contain 'http://'.
$req->http_port
Returns the port the client used in this request.
$req->http_scheme
Returns the scheme the client used in this request.
Either http or https
$req->http_if_modified_since
Returns the time as an Para::Frame::Time object.
If no such time was given with the request, returns undef.
$req->client_ip
Returns the ip address of the client as a string with dot-separated numbers.
$req->set_site( $site )
Sets the site to use for this request.
$site should be the name of a registred Para::Frame::Site or a
site object.
The site must use the same host as the request.
The method works similarly to Para::Frame::File/set_site
Returns: The site object
$req->site
The site for the request is used for actions.
It may not be the same as the site of the response page as given by
$req->page->site. But will in most cases be the same since
it's set in the same way as the initial site for the response page.
But in some cases there will be no page (as for background jobs), and thus no page site.
Make sure to set the request site along with the page site, if it's to change and any futher actions in the request should use that new site.
Returns the Para::Frame::Site object for this request.
$req->host
Returns the host name used for accessing this host. Includes :$port
if port differs from 80.
$req->host_without_port
Returns the host name used for accessing this host, without the port part.
$req->host_with_port
Returns the host name used for accessing this host, with the port part.
$req->create_fork
Creates a fork.
In PARENT, returns a Para::Frame::Child object.
In CHILD, returnt a Para::Frame::Child::Result object.
Then the child returns. The hook child_result is runt with the
Para::Frame::Result object as the param after $req.
You must make sure to exit the child. This is supposed to be done by the Para::Frame::Result/result method.
The hook on_fork is run in the CHILD just after the
Para::Frame::Result object is created.
Example 1 uses Para::Frame::Child::Result/on_return. Example 2 uses Para::Frame::Child/yield. The first method (example 1) is preferred as it is safer and faster in certain cases.
Example 1:
my $fork = $req->create_fork;
if( $fork->in_child )
{
# Do the stuff...
$fork->on_return('process_my_data');
$fork->return($my_result);
}
return "";
sub process_my_data
{
my( $result ) = @_;
# Do more stuff
return "All done now";
}
Example 2:
my $fork = $req->create_fork;
if( $fork->in_child )
{
# Do the stuff...
$fork->return($my_result);
}
$fork->yield; # let other requests run
return $fork->result;
$req->run_hook( $label, @args );
$req->note( $text )
Sending text to show during loading of a page.
Usable for progress indication.
$req->set_response( $url, \%args )
$req->reset_response()
Uses current /page if existing.
If this is the first time, sets the URL from the req as the original page. The original page can be retrieved via /original_response.
Should be used if we may want to use another template based on a changed language or something else in the context that has changed.
Calls /set_response and returns that response.
$req->error_page_selected
True if an error page has been selected
$req->error_page_not_selected
True if an error page has not been selected
$req->original_response
$req->original_url
$req->original_url_string
$req->original_url_with_query
$req->original_url_params
The query string passed as part of the URL
Not including any POST data.
Used by Para::Frame::Request::Response/page_url_path_with_query_and_reqnum
Returns: the unparsed string, after the '?', as given by $ENV{'QUERY_STRING'}. Saved on Req startup.
Sets the Para::Frame::Request::Response appropriate for the error.
If the session object can Para::Frame::Session/go_login and the
method returns true, it will be used instead of a redirection to
/login.tt template.
Jonas Liljegren <jonas@paranormal.se>