MT::Telegraph::Agent / Knowledge Base / Appnel Solutions

Last Modified
9 January 2007 @ 3pm

MT::Telegraph::Agent

NAME

MT::Telegraph::Agent - A client for interfacing with a remote HTTP resources

VERSION

Telegraph 0.62

SYNOPSIS

  use MT::Telegraph;
  use MT::Telegraph::CacheMgr;
  use MT::Telegraph::Agent;

  MT::Telegraph::Agent->add_callback('404',5,undef,&log_404);

  my $uri = 'http://www.example.com/';
  my $dir = '/path/to/cache/directory';

  my $cache =
    MT::Telegraph::CacheMgr->new('File', {cache_root => $dir })
      or die MT::Telegraph::CacheMgr->errstr;
      
  my $agent = MT::Telegraph->agent;
  my $content = MT::Telegraph->fetch($uri,$cache,{ agent => $agent });

  sub log_404 {
    my ($eh, $res) = @_;
    MT::Log('Not Found:'.$res->uri);
  }

DESCRIPTION

An agent is the client interface (browser if you please) used to manage HTTP requests and their subsequent responses.

MT::Telegraph::Agent wraps LWP::UserAgent for use within Movable Type and Telegraph and is used in close coordination with the cache system. It can be used as a base class from developing specialized agent classes. These specialized agents may implement a different constructor, different configuration, add additional functionality or callback hooks.

Typically a developer will only ever directly call add_callback. All other methods are called through the MT::Telegraph agent method or by URI::Fetch or LWP::UserAgent while fetching a resource.

A developer will need to be familiar with the callbacks and class structure to build applications and plugins in the framework.

METHODS

The following methods are implemented in MT::Telegraph::Agent:

new(\%params)
The constructor that returns an agent object. An option HASH reference of parameters can be provided. The MT::Telegraph::Agent doesn't have any particular use for the HASH, but passes it through to its base class, LWP::UserAgent.

In addition to constructing a new agent object and passing through any parameters, this class restricts redirected requests to HTTP GET and HEAD methods and sets the User-Agent identifier is set to the class name and version number of Telegraph.
agent
Gets the slug that is used to identify the user agent on the network. The agent value is sent as the User-Agent header in the HTTP requests.
add_callback($hook, $priority, $plugin, $code)
Registers a new callback handler for a particular callback hook.

The first parameter is the name of the callback hook.

The second parameter is a priority (a number in the range of 1-10) which will control the priority that the handler is executed. If two handlers register with the same priority, they will be executed in the order that they registered.

The third parameter is an optionl MT::Plugin object reference that is associated with the handler.

The fourth parameter is a code reference that is invoked to handle the callback.

This method appends the agent's class name and two colon's to the hook name ($hook) and calls the add_callback method in the MT class. The following two statement would have the same identical effect:
```
  MT::Telegraph->add_callback('Content',5,$plugin, &code);

  MT->add_callback('MT::Telegraph::Content',5,$plugin,&code);
```

Callback Methods

The following methods are a different form of callbacks then what is typically found in Movable Type and what is detailed in the CALLBACKS section.

These callback methods are made available by the underlying LWP::UserAgent class uses. The methods will be invoked as requests are processed. The base Telegraph agent uses them to fire the callback hooks listed in CALLBACKS.

These hooks offer a couple distinct advantages to developers.

They are encapsulated in the agent class and do not need to be registered like typical MT callbacks.
One handler per hook
These methods are fired before any callbacks registered through the add_callback method.
These methods can be used to kill or optionally execute callbacks registered using add_callback.

These callback methods are as follows:

content_alter_hook($content)
This isn't actually a method from LWP::UserAgent, however; for consistency this method was implemented.

A method that is called with a SCALAR reference to the content of a response so it can modified before it's cached.

MT::Telegraph::Agent runs any Content hooks in this method.
cache_entry_grep($response)
This isn't actually a method from LWP::UserAgent, however; for consistency this method was implemented.

This method is called with the URI::Fetch::Response object (whose contents may have been altered by a callback) that is about to be passed into the cache manager. If the method returns TRUE, the response goes into the cache. If FALSE is returned it is discarded.

MT::Telegraph::Agent runs any CacheFilter hooks in this method.
$agent->prepare_request($request)
A method used to modify the given HTTP::Request object ($request) by setting up various HTTP headers. A HTTP::Request object must be returned. Typically this is the request object passed in, however; if a different request object is returned, processing will continue on the new request object that is returned.

MT::Telegraph::Agent runs any Request hooks in this method.
redirect_ok($prospective_request, $response)
A method that is called before the agent tries to follow a redirection to the request in the HTTP::Response ($response) object. This method is a filter and should return a TRUE value if this redirection is permissible. The method also passes a HTTP::Request object ($prospective_request) that is the request to be sent if this method returns TRUE.

MT::Telegraph::Agent runs any Redirect hooks in this method.

get_basic_credentials has not been implemented at this time.

CALLBACKS

Telegraph supports a number of callback hooks in the framework that can be used by developers to create plugins for any Telegraph enabled software.

These callback hooks are registered using the add_callback class method that is detailed in the METHODS section.

MT::Telegraph::Agent implements the following named hooks:

Content
A hook for modifying the content of a response before it's cached.

Content callback handlers are passed an error handler object, a URI object and a SCALAR reference to the response content.

The return value of a Content callback is ignored.
CacheFilter
A hook to act on and filter content going into the cache.

CacheFilter callback handlers are passed an error handler object, a URI object and the URI::Fetch::Response object about to be cached.

All Content callback handlers will have been run on the response object by the time any CacheFilter callbacks are run.

Returning TRUE will allow the content to be cached and processing to continue. If a CacheFilter callback or any other returns FALSE, the response content is not cached, but discarded.
Request
A hook that can be used to modify the given HTTP::Request object by a fetch is made.

CacheFilter callback handlers are passed an error handler object, the agent object and the HTTP::Request object that will be used to fetch the resource.

Unlike the prepare_request method the request object can not be substituted.

The return value of a Request callback is ignored.
Redirect
A hook to act on and filter further processing of a redirect response.

Redirect callback handlers are passed an error handler object, the agent object, the proposed HTTP::Request object that will be used to issue the follow-up request and a HTTP::Response object representing the redirect response from the server.

Returning TRUE will allow the agent to issue another request to the redirected URI. If a Redirect callback or any other returns FALSE, the follow-up response will not issued.

NOTE: Subclasses of MT::Telegraph::Agent can implement addition callback hooks as deemed appropriate to is purpose. Please refer to each agent's documentation for more detail.

HTTP Status Callbacks

In addition to the named callback hooks that have been listed, MT::Telegraph::Agent also provides hooks to any standard HTTP status code except for 200 (OK) which is represented by all the previously mentioned hooks.

HTTP status callbacks are registered by their HTTP status code number. For instance, to register a hook for handling a 404 (Not Found) status response you would use this statement:

  MT::Telegraph::Agent->add_callback('404',5,$plugin,&not_found);

With this statement, any time MT::Telegraph fetches a resource using its default agent class and receives a 404 status message back from the server MT will execute the not_found method.

HTTP status callback handlers are passed an error handler object, the agent object, the URI::Fetch::Response object.

The return value of any HTTP status callback will be ignored.

TO DO

Need to implement a get_basic_credentials method and callback hook for handling HTTP Basic Authentication requests.

AUTHOR & COPYRIGHT

Submit Feedback on This Article

Your comments on how we can improve this article are appreciated. Please do not use the feedback form to submit support requests or question. We will not respond to or publish such queries submitted through this form.

Name:

Email Address:

URL:

Remember personal info?

Comments:

Comments will be moderated and may appear on this page or be incorporated into future versions of this document.