Package pyxmpp :: Module cache :: Class CacheFetcher
[show private | hide private]
[frames | no frames]

Class CacheFetcher

Known Subclasses:
DiscoCacheFetcherBase

Base class for cache object fetchers -- classes responsible for
retrieving objects from network.

An instance of a fetcher class is created for each object requested and
not found in the cache, then `fetch` method is called to initialize
the asynchronous retrieval process. Fetcher object's `got_it` method
should be called on a successfull retrieval and `error` otherwise.
`timeout` will be called when the request timeouts.

:Ivariables:
    - `cache`: cache object which created this fetcher.
    - `address`: requested item address.
    - `timeout_time`: timeout time.
    - `active`: `True` as long as the fetcher is active and requestor
      expects one of the handlers to be called.
:Types:
    - `cache`: `Cache`
    - `address`: any hashable
    - `timeout_time`: `datetime`
    - `active`: `bool`

Method Summary
  __init__(self, cache, address, item_freshness_period, item_expiration_period, item_purge_period, object_handler, error_handler, timeout_handler, timeout_period, backup_state)
Initialize an `CacheFetcher` object.
  error(self, error_data)
Handle a retrieval error and call apriopriate handler.
  fetch(self)
Start the retrieval process.
  got_it(self, value, state)
Handle a successfull retrieval and call apriopriate handler.
  timeout(self)
Handle fetcher timeout and call apriopriate handler.
  _deactivate(self)
Remove the fetcher from cache and mark it not active.
  _deactivated(self)
Mark the fetcher inactive after it is removed from the cache.
  _try_backup_item(self)
Check if a backup item is available in cache and call the item handler if it is.

Method Details

__init__(self, cache, address, item_freshness_period, item_expiration_period, item_purge_period, object_handler, error_handler, timeout_handler, timeout_period, backup_state=None)
(Constructor)

Initialize an `CacheFetcher` object.

:Parameters:
    - `cache`: cache object which created this fetcher.
    - `address`: requested item address.
    - `item_freshness_period`: freshness period for the requested item.
    - `item_expiration_period`: expiration period for the requested item.
    - `item_purge_period`: purge period for the requested item.
    - `object_handler`: function to be called after the item is fetched.
    - `error_handler`: function to be called on error.
    - `timeout_handler`: function to be called on timeout
    - `timeout_period`: timeout interval.
    - `backup_state`: when not `None` and the fetch fails than an
      object from cache of at least this state will be passed to the
      `object_handler`. If such object is not available, then
      `error_handler` is called.
:Types:
    - `cache`: `Cache`
    - `address`: any hashable
    - `item_freshness_period`: `timedelta`
    - `item_expiration_period`: `timedelta`
    - `item_purge_period`: `timedelta`
    - `object_handler`: callable(address, value, state)
    - `error_handler`: callable(address, error_data)
    - `timeout_handler`: callable(address)
    - `timeout_period`: `timedelta`
    - `backup_state`: `bool`

error(self, error_data)

Handle a retrieval error and call apriopriate handler.

Should be called when retrieval fails.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).

:Parameters:
    - `error_data`: additional information about the error (e.g. `StanzaError` instance).
:Types:
    - `error_data`: fetcher dependant

fetch(self)

Start the retrieval process.

This method must be implemented in any fetcher class.

got_it(self, value, state='new')

Handle a successfull retrieval and call apriopriate handler.

Should be called when retrieval succeeds.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).

:Parameters:
    - `value`: fetched object.
    - `state`: initial state of the object.
:Types:
    - `value`: any
    - `state`: `str`

timeout(self)

Handle fetcher timeout and call apriopriate handler.

Is called by the cache object and should _not_ be called by fetcher or
application.

Do nothing when the fetcher is not active any more (after
one of handlers was already called).

_deactivate(self)

Remove the fetcher from cache and mark it not active.

_deactivated(self)

Mark the fetcher inactive after it is removed from the cache.

_try_backup_item(self)

Check if a backup item is available in cache and call
the item handler if it is.

:return: `True` if backup item was found.
:returntype: `bool`

Generated by Epydoc 2.1 on Wed May 31 22:37:02 2006 http://epydoc.sf.net