GX::Context

Module Version: 0.2000_01

NAME

GX::Context - Context component

SYNOPSIS

package MyApp::Context;

use GX::Context;

1;

DESCRIPTION

This module provides the GX::Context class which inherits directly from GX::Component and GX::Class::Object.

METHODS

Constructor

new

Returns a new context object.

$context = $class->new( %attributes );
Attributes:
  • action_queue ( GX::Callback::Queue object )

    An action queue object.

  • dispatch_stack ( ARRAY reference )

    An array reference.

  • error ( scalar )

    An error message or object, preferably a GX::Exception instance.

  • error_stream ( object )

    An error stream object.

  • handler_queue ( GX::Callback::Hook::Queue object )

    A handler queue object.

  • input_stream ( object )

    An input stream object.

  • output_stream ( object )

    An output stream object.

  • request ( GX::Request object )

    A request object.

  • response ( GX::Response object )

    A response object.

  • sessions ( HASH reference )

    A reference to a hash of GX::Session class / instance pairs.

  • stash ( HASH reference )

    A hash reference.

  • time ( integer )

    The UNIX time associated with the request.

  • user ( object )

    An user object.

Returns:
Exceptions:

Public Methods

abort

Aborts the dispatch phase after returning from the current callback.

$context->abort;

Implementation details: Calling abort() clears all dispatch queues in the dispatch stack and the action queue.

action

Returns the action that is currently being dispatched, or undef if called outside the dispatch phase.

$action = $context->action;
Returns:

bail_out

Aborts the processing of the current request after returning from the current callback.

$context->bail_out;

Implementation details: Calling bail_out() clears all dispatch queues in the dispatch stack, the action queue and the handler queue.

controller

Returns the controller instance to which the currently dispatched action belongs, or undef if called outside the dispatch phase.

$controller = $context->controller;
Returns:

dispatch

Adds the specified action to the end of the action queue, so it will be dispatched after any actions already in that queue.

$context->dispatch( %arguments );
Arguments:
  • action ( string | GX::Action object ) [ required ]

    An action name or action object.

  • controller ( string | GX::Controller object )

    A qualified or unqualified controller name or a controller instance. Optional. Defaults to the controller to which the currently dispatched action belongs. Discarded if an action object is passed for action.

Exceptions:

Alternative syntax:

$context->dispatch( $action );
Arguments:
  • $action ( string | GX::Action object )

    An action name or action object. If an action name is passed, the action is assumed to belong to the same controller as the currently dispatched action.

Exceptions:

done

Ends the dispatch phase.

$context->done;

Implementation details: Calling done() removes any undispatched actions from the action queue.

error

Returns / sets the current error.

$error = $context->error;
$error = $context->error( $error );
Arguments:
  • $error ( scalar ) [ optional ]

    An error message or object, preferably a GX::Exception instance.

Returns:
  • $error ( scalar )

forward

Forwards processing to the specified action after returning from the current callback.

$context->forward( %arguments );
Arguments:
  • action ( string | GX::Action object ) [ required ]

    An action name or action object.

  • controller ( string | GX::Controller object )

    A qualified or unqualified controller name or a controller instance. Optional. Defaults to the controller to which the currently dispatched action belongs. Discarded if an action object is passed for action.

Exceptions:

Implementation details: Calling forward() clears all dispatch queues in the dispatch stack and replaces all actions in the action queue with the specified action.

Alternative syntax:

$context->forward( $action );
Arguments:
  • $action ( string | GX::Action object )

    An action name or action object. If an action name is passed, the action is assumed to belong to the same controller as the currently dispatched action.

Exceptions:

When called without arguments, forward() forwards processing to the next action in the action queue.

$context->forward;

Implementation details: In this case, calling forward() only clears all dispatch queues in the dispatch stack.

handler

Returns the handler that is currently being executed.

$handler = $context->handler;
Returns:

hook

Returns the hook to which the handler that is currently being executed belongs.

$hook = $context->hook;
Returns:

path_for_action

Constructs the path portion of an URI that would match the reverse route of the specified action. Returns the constructed path or, if no reversible route is associated with the respective action, undef.

$path = $context->path_for_action( %arguments );
Arguments:
  • action ( string | GX::Action object )

    An action name or action object. Optional. Defaults to the currently dispatched action.

  • controller ( string | GX::Controller object )

    A qualified or unqualified controller name or a controller instance. Optional. Defaults to the controller to which the currently dispatched action belongs. Discarded if an action object is passed for action.

  • parameters ( HASH reference )

    A reference to a hash with values for the dynamic parts of the path.

Returns:
  • $path ( string | undef )
Exceptions:

This method is basically a thin, context-aware wrapper around the GX::Router method of the same name.

Alternative syntax:

$path = $context->path_for_action( $action );
Arguments:
  • $action ( string | GX::Action object ) [ optional ]

    An action name or action object. Optional. Defaults to the currently dispatched action. If an action name is passed, the action is assumed to belong to the same controller as the currently dispatched action.

Returns:
  • $path ( string | undef )
Exceptions:

redirect

Aborts the dispatch phase (see abort()) and redirects the client to the specified URI.

$context->redirect( %arguments );
Arguments:
  • status ( integer )

    The HTTP status code of the response. Defaults to "302".

  • uri ( string ) [ required ]

    The URI to redirect the client to.

Exceptions:

Implementation details: See abort().

Alternative syntax:

$context->redirect( $uri );
Arguments:
  • $uri ( string )

    See above.

Exceptions:

render

Renders the specified view.

$context->render( view => $view, ... );
Arguments:
  • view ( string | GX::View object )

    A qualified or unqualified view name or a view instance.

  • Any other arguments are passed through to the render() method of the specified view.
Exceptions:

Alternative syntax:

$context->render( $view );
Arguments:
  • $view ( string | GX::View object )

    A qualified or unqualified view name or a view instance.

Exceptions:

If called without arguments, render() triggers the renderer that is associated with the current action.

$context->render;
Exceptions:

render_as

Triggers the specified format handler of the renderer that is associated with the current action.

$context->render_as( $format );
Arguments:
  • $format ( string )

    A format identifier.

Exceptions:

renderer

Returns the renderer that is associated with the current action.

$renderer = $context->renderer;
Returns:

request

Returns / sets the request object.

$request = $context->request;
$request = $context->request( $request );
Arguments:
Returns:

response

Returns / sets the response object.

$response = $context->response;
$response = $context->response( $response );
Arguments:
Returns:

send_response

Aborts further processing of the request and forces the response to be sent immediately after returning from the current callback.

$context->send_response;
Exceptions:

If send_response() is called without arguments, the response will be sent as is. Otherwise, the current response is discarded and a new response is constructed based on the given arguments.

$context->send_response( %arguments );
Arguments:
  • body ( GX::HTTP::Body object )

    A body object containing the response body. This argument cannot be combined with the file, render or render_hint argument.

  • file ( string )

    The path to a file to send as the response body. This argument cannot be combined with the body, render or render_hint argument.

  • headers ( GX::HTTP::Response::Headers object | HASH reference )

    A response headers object or a reference to a hash containing header field / value pairs.

  • render ( string | GX::View object | ARRAY reference | HASH reference )

    A render directive. See render for details. This argument cannot be combined with the body, file or render_hint argument.

  • render_hint ( string | GX::View object | ARRAY reference | HASH reference )

    Same as render above, but does not complain if the specified view does not exist. This argument cannot be combined with the body, file or render argument.

  • status ( integer )

    The HTTP status code of the response. Defaults to "200".

Exceptions:

Implementation details: Calling send_response() clears all dispatch queues in the dispatch stack, clears the action queue and skips all handlers in the handler queue up to the FinalizeResponse hook.

session

Returns the instance of the specified session component or, if called without arguments, of the default session component.

$session = $context->session( $session_name );
Arguments:
  • $session_name ( string ) [ optional ]

    A qualified or unqualified session component name.

Returns:
  • $session ( GX::Session object | undef )

    The instance of the specified / default session component, or undef if the application has no such component.

sessions

Returns all session component instances.

@sessions = $context->sessions;
Returns:

stash

Returns a reference to the stash.

$stash = $context->stash;
Returns:
  • $stash ( HASH reference )

time

Returns the UNIX time associated with the request.

$time = $context->time;
Returns:
  • $time ( integer )

uri_for_action

Constructs an URI that would match the reverse route of the specified action. Returns the constructed URI or, if no reversible route is associated with the respective action, undef.

$uri = $context->uri_for_action( %arguments );
Arguments:
  • action ( string | GX::Action object )

    An action name or action object. Optional. Defaults to the currently dispatched action.

  • controller ( string | GX::Controller object )

    A qualified or unqualified controller name or a controller instance. Optional. Defaults to the controller to which the currently dispatched action belongs. Discarded if an action object is passed for action.

Additional, route-dependent arguments:
  • fragment ( string )

    The fragment identifier of the URI.

  • host ( string )

    The hostname to use as the authority component of the URI. Defaults to $context->request->host.

  • parameters ( HASH reference )

    A reference to a hash with values for the dynamic parts of the URI.

  • path ( string )

    The path portion of the URI.

  • port ( integer )

    The port number to append to the hostname. Defaults to $context->request->port.

  • query ( string )

    The query component of the URI.

  • scheme ( string )

    The scheme part of the URI. Defaults to $context->request->scheme.

Returns:
  • $uri ( string )
Exceptions:

This method is basically a thin wrapper around the GX::Router method of the same name.

Alternative syntax:

$uri = $context->uri_for_action( $action );
Arguments:
  • $action ( string | GX::Action object ) [ optional ]

    An action name or action object. Optional. Defaults to the currently dispatched action. If an action name is passed, the action is assumed to belong to the same controller as the currently dispatched action.

Returns:
  • $uri ( string )
Exceptions:

user

Returns / sets the associated user object.

$user = $context->user;
$user = $context->user( $user );
Arguments:
  • $user ( object | undef ) [ optional ]
Returns:
  • $user ( object | undef )

Internal Methods

action_queue

Returns / sets the action queue object.

$queue = $context->action_queue;
$queue = $context->action_queue( $queue );
Arguments:
Returns:

dispatch_queue

Returns the current dispatch queue object.

$queue = $context->dispatch_queue;
Returns:

dispatch_stack

Returns a reference to the dispatch stack.

$stack = $context->dispatch_stack;
Returns:
  • $stack ( ARRAY reference )

error_stream

Returns / sets the error stream object.

$stream = $context->error_stream;
$stream = $context->error_stream( $stream );
Arguments:
  • $stream ( object ) [ optional ]
Returns:
  • $stream ( object )

handler_queue

Returns / sets the handler queue object.

$queue = $context->handler_queue;
$queue = $context->handler_queue( $queue );
Arguments:
Returns:

input_stream

Returns / sets the input stream object.

$stream = $context->input_stream;
$stream = $context->input_stream( $stream );
Arguments:
  • $stream ( object ) [ optional ]
Returns:
  • $stream ( object )

output_stream

Returns / sets the output stream object.

$stream = $context->output_stream;
$stream = $context->output_stream( $stream );
Arguments:
  • $stream ( object ) [ optional ]
Returns:
  • $stream ( object )

AUTHOR

Jörg A. Uzarek <uzarek@runlevelnull.de>

COPYRIGHT AND LICENSE

Copyright © 2009-2011 Jörg A. Uzarek.

This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License Version 3 as published by the Free Software Foundation.