Knowledge Base / Appnel Solutions 

MT::Telegraph

NAME

Telegraph - A general purpose framework for fetching and caching web content in Movable Type.

VERSION

0.62

SYNOPSIS

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

  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 });

DESCRIPTION

Telegraph is a general purpose framework for fetching and caching web content in Movable Type such as syndication feeds. It is based on the experience gained from developing Feeds.App was extracted from the development of version 3 of the plugin.

The Telegraph framework provides developers with three core areas functionality that can be configured or extended:

• Agent

  An agent is the client interface (browser if you may) used to manage HTTP requests and their subsequent responses. A Telegraph agent provides a series of callback hooks an application or other plugins can use to extend its functionality.

  See MT::Telegraph::Agent for more detail.

• Cache Manager

  The cache manager handles the local storage and management of content retrieved by Telegraph agents. Caching is used to reduce bandwidth usage and speed processing.

  The cache manager interface is modeled after Cache package found in CPAN.

  The Telegraph Cache Manager comes with drivers for local file system and MT::Object caching of data.

  See MT::Telegraph::CacheMgr for more details.

• Logging

  Telegraph also provides a logging class for recording HTTP specific entries in the MT Activity Log.

  See MT::Log::Telegraph for more details.

METHODS

MT::Telegraph provides the two core methods that are most commonly used by any Telegraph-enabled application.

• MT::Telegraph->agent(\%params)

  Creates and returns an agent object that configured using Movable Type's configuration for making HTTP requests. Configuration directives used are HTTPProxy, HTTPNoProxy, HTTPTimeout and HTTPInterface. PingProxy, PingNoProxy, PingTimeout and PingInterface are checked if their HTTP counterpart is not defined. NOTE: the Ping directives are considered deprecated and should not be used.

  A HASH reference contain parameters may be passed. The recognized parameters are as follows.

  • agent_class

    Defines the agent class to construct the resulting object from. Agents must have an interface like MT::Telegraph::Agent and typically will descend from this class.

    If agent_class is not defined, MT::Telegraph::Agent is used.

  • proxy

    The full URL address of a proxy server to route all HTTP requests through.

    If undefined, the method will use the MT directive HTTPProxy and then PingProxy if set.

  • no_proxy

    Defines a list of domain that should NOT be routed through the configured proxy. This list is a comma-separated list.

    If undefined, the method will use the MT directive HTTPNoProxy and PingNoProxy if set.

  • timeout

    The number of seconds that the agent should wait before giving up on an HTTP request.

    If undefined the method will check if the MT directive HTTPTimeout and PingTimeout in that order.

  The agent method will set the HTTP interface using HTTPInterface or PingInterface if set. If HTTP requests are to be sent over a network interface card (NIC) other then the server's default, this directive will be set to configure it properly.

• MT::Telegraph->fetch($uri, $cache, \%param)

  Makes a request to the URI and returns the response as a URI::Fetch::Response object.

  This method requires an absolute URI, represented as a string or a URI object, and a MT::Telegraph::CacheMgr object to make a request. An optional HASH reference of parameters can also be passed in. Recognized parameters are as follows:

  • ttl

    The ttl (time to live) parameter controls the interaction between the cache and HTTP requests with If-Modified-Since/If-None-Match headers.

    For clarity two constants of CHECK_ALWAYS (0) and CACHE_ONLY (1) can be used from this class.

    Possible behaviors are:

    • CHECK_ALWAYS (default)

      The HTTP server should always checked for a fresher copy with an If-Modified-Since and/or If-None-Match header.

    • CACHE_ONLY

      If set to CACHE_ONLY (1), the HTTP server should never be contacted, regardless of what is in the cache. If nothing is present in the cache, undef will be returned. If something is present in the cache, the cached copy will be returned no matter how old it is. NOTE: setting this option means the URI::Fetch::Response object will never have the http_response member set.

    • N, where N > 1

      The HTTP server should not be contacted if a copy is in cache and was added or modified in the last N seconds. If the cached copy is older than N seconds, a normal HTTP request (full or cache check) is done.

  • agent

    An existing Telegraph agent object to use in making the request. If a agent object is not passed one is instantiated using the classes agent object. It's recommended that you pass an agent object in with each request to avoid the unnecessary overhead of creating one with each request.

  During a fetch, several callback hooks can be fired depending upon the response. See CALLBACKS in MT::Telegraph::Agent for more details.

  Rather then access the cache directly if the resource has not been updated or is unreachable, fetch transparently handles it for you.

CALLBACKS

The Telegraph framework supported a number of callback hooks in the framework. These hooks are defined in MT::Telegraph::Agent where they are set, managed and invoked.

DEPENDENCIES

• Movable Type 3.3 or Movable Type Enterprise 1.02
• MT::Log::Base
• LWP
• URI
• URI::Fetch 0.06

AUTHOR & COPYRIGHT

Copyright 2005-2007 Appnel Internet Solutions, LLC, info@appnel.com. All Rights Reserved. This code cannot be redistributed without permission of the author.