/ 
Agent-TCLI-0.030
River stage one • 1 direct dependent • 1 total dependent
/ Agent::TCLI::Request

NAME

Agent::TCLI::Request - A Request class for Agent::TCLI::Request.

SYNOPSIS

An object for storing Agent::TCLI::Request information. Used by Transports and not externally accessible at this point.

OVERVIEW

Requests are the basic transaction in TCLI. In the simplest form, they are created by Control for sending to the Command to perform the Request. Requests come with their own Respond method that will generate a Response object, so that Commands do not need to implement that logic.

In the more complex form, Requests may be handled directly by Transports. Of course, Transports do not process a Request, they merely move them. If a Transport if acting on a Request (or the Reponse) it must have it's own logic for doing so. In order to facilitate this process, sender and postback attrbutes are arrays, so that they may be stacked. The Respond method will remove the entries from the stack.

ATTRIBUTES

The following attributes may be accessed through a combined mutator. If the attribute is an array type, then additional array mutators are available and described below. In addition, Agent::TCLI::Request suports Auto-Attributes as described below.

id

Id for request tracking. Must be unique for each request. One should probably just let the object set it automatically.

args

The request's arguments as parsed into an array. Usually built by the Agent::TCLI::Control, but may be set up externally as well. args will only accept ARRAY type values. Since args is an array, it is often best use one of the mutator methods listed below.

command

An array containing the prmoinent verb for this request, followed by the rest of the context the command was issued in reversed. command will only accept ARRAY type values. Since command is an array, it is often best use one of the mutator methods listed below.

sender

The POE session making the request, so that the response can be returned properly. It is also the Tranport used when going between agents.

postback

The event to post the response back to. It is also the return addressee when going between agents.

input

The exact, unparsed input string from the user. This might be useful for some commands, but mostly is ignored. If not provided it should be automatically generated from the command and args if necessary.

response_count

A counter that is incremented for every response to this request. This is updated automatically through the use of the Respond method. response_count will only accept NUMERIC type values.

response_verbose

A setting that determines how much of the request information is returned with the response. If true, the entire request will be returned. If false, only the required fields will be. response_verbose should only contain boolean values.

Arrays

Attributes that are typed as arrays also support the following mutators for the lazy: shift_>field< - works the same as shift, returing the shifted member. unshift_>field<(list) - works the same as unshift. pop_>field< - works the same as pop, returing the popped member. push_>field<(list) - works the same as push. depth_>field< - returns the curent size of the array.

Auto-Attributes

Agent::TCLI::Request has an AutoMethod routine that can create object attributes on the fly. These all use lower case set_/get_ mutators which differentiates them from the pre-defined attributes. Since all responses should contain the original Request object, this is a handy way to pass stateful information about the Request to the postback handling the response.

For example: $request->set_test('like');

If the new attribute name contains 'array', it is created as an array type and the array mutators listed above will apply.

METHODS

MakeResponse ( <text>, <code> )

MakeResponse used internally by Respond to create the Response object to send back to the requestor. The only reason to call MakeResponse directly would be to add or remove attributes before the Response is sent.

Respond ( <poe_kernel>, <text> [, <code>]) or ( <poe_kernel>, <response obj> )

Respond is the proper way to return a response to a request. It requires a reference to the poe_kernel as the first parameter. The second parameter may be either some text for the response or a Response object. The third parameter is the resposne code. If not provided, it defaults to 200. While not required, it is best to always fill in the response code. The response code will be ignored if a Response object is provided.

INHERITED METHODS

This module is an Object::InsideOut object that inherits from Agent::TCLI::Base. It inherits methods from both. Please refer to their documentation for more details.

AUTHOR

Eric Hacker <hacker at cpan.org>

BUGS

The (ab)use of AUTOMETHODS is probably more a bug than a feature.

SHOULDS and MUSTS are currently not always enforced.

Test scripts not thorough enough.

LICENSE

Copyright (c) 2007, Alcatel Lucent, All rights resevred.

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