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 extarnally 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.
TODO: Do I need to have a thread in the Request? I think all the commands will know their context and not need to pull that from the thraed? No, that's how it is getting passed from control. A contreol is created within the thread, so we really shouldn't need it? Ah, but the Commands are created outside of the Control as separate POE::Sessions, so it is. However, since the Control should know it's own thread, we could pop it off at the response, like with the sender and postback.
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 hte 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<(list) - 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.
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.
Probably many others.
LICENSE
Copyright (c) 2007, Alcatel Lucent, All rights resevred.