NAME

Notify::NoticePool - Framework for managing persistent user notifications.

SYNOPSIS

 use Notify::NoticePool;
 use Notify::Notice;
 use Notify::Email;

 my $email_transport = new Notify::Email ({
     'app'   => "Application Name",
     'mbox'  => "/var/spool/mail/mailbox",
     'smtp'  => "smtp.domain.net",
 });

 my $notice_pool = new Notify::NoticePool ({
     'file_store'  => "/usr/lib/persistent_db",
     'transport'   => { 'email' => $email_transport },
 });

 # Add a notification
 my $id = $notice_pool->getUniqueID ();
 my $notice = new Notify::Notice ({
     'id' => $id,
 });
 # ... set attributes
 $notice_pool->addNotice ($notice);

# Retreive a notification if one is waiting
 my $notice = new Notify::Notice ({
     'id' => $id,
     'transport' => 'email',
 });
 $notice_pool->retrieveNotice ($notice);

 # Advance each transaction if possible
 $notice_pool->updateOutstanding ();

DESCRIPTION

Notify::NoticePool provides methods for managing persistent user notifications that might be sent through a variety of medium such as via email or pager. This module is meant to facilitate communication through medium where the programmer can expect a significant delay and where reliability is important.

NoticePool allows for management of various Notification objects (see Notify::Notice), each with possibly different destinations. The NoticePool offers guaranteed reliability as all changes to the Notification object are written out to disk in the notification database prior to update.

The notification pool allows the addition, updating, and retrieval of notification objects within the pool. Notification transactions are advanced through the 'updateOutstanding' method, which attempts to resend notifications whose delivery previously failed and indicate that notices are awaiting processing when a response has arrived.

Transports are registered as transport types (keywords) and associated instantiated transport objects. Transport objects must adhere to the interface outlined in the transport section below.

A history of the notification transactions is also maintained within the notification object during sending and retrieval. The status of the notification object is also updated as the application interacts with the notice pool.

Finally, notification objects continue to exist within the persistent notification database until they are resolved by the application.

EXPORT

None by default.

CLASS ATTRIBUTES

$Notify::NoticePool:resend_interval
    - The interval at which to retry a failed attempt to
      send a notification

$Notify::NoticePool:max_retries
    - The maximum number of retries before a notification
      is deemed a failure.

$Notify::NoticePool:VERSION
    - The CVS revision of this module.

The following class constants are optional:

DEFAULT_MAX_RESEND_INTERVAL - The default interval in
                              seconds at which to retry a
                              failed attempt.

DEFAULT_MAX_RETRIES - The default number of retries before
                      deeming a notification a failure.

PUBLIC METHODS

new ($hashref)

   The constructor takes a hashref that support the following
   keys:

     Required:

       'file_store' - The persistent database to use.
       'transport'  - A hashref whose keys are the names of
                      transport types and whose values are
                      instantiated transport objects.

     Optional:

       'no_implicit_update' - When this key is set,
                              updateOutstanding will not be
                              called during object
                              instantiation.

setResendInterval ($integer)

   Sets the miniumum interval that must elapse in seconds
   between failed notifications. Note that the notifications
   will only be resent with a call to updateOutstanding ().

getResentInterval ()

   Returns the interval value.

setMaxRetries ($integer)

   Sets the number of retries to attempt before marking a
   notification a failure.

getMaxRetries

   Returns the maximum number of retries.

addTransport ($hashref)

   Takes a hashref whose keys are transport types and whose
   values are instantiated transport objects. These are used
   when routing the notification objects based on the 'type'
   field.

getUniqueID ()

   Returns a unique ID (currently unused in the persistent
   database) for the creation of a new notification object.

exits ($id)

   Retruns 1 if an ID exists within the persistent
   database and 0 otherwise.

addNotice ($notice)

   Adds a notice object into the pool. Returns undef if the
   add failed (i.e, a notification object with the same id
   already exists) or an updated notification object if
   successful. An attempt to send the notification is
   immediately made as well.

resolveNotice ($notice)

   Resolves a notification by removing it from the persistent
   database. Returns 1 if successful, otherwise returns
   undef.

retrieveNotice ($object)

   Attempts to receive the response associated with a
   notification object. Returns a new notification object
   that includes the new response message and the updated
   history.

updateNotice ($notice)

   Updates the attributes of an existing notice within the
   persistent database. Returns an updated notification
   object if successful and undef otherwise.

updateOutstanding ()

   Checks all notifications in the persistent database and
   attempts to advance each transaction by one step, i.e,
   resending failed attempts or checking if a response is
   waiting for a notification. This method changes the
   status of the notification in the persistent database
   accordingly.

PRIVATE METHODS

sendIfAppropriate ($notice)

   Attempts to send the notice if the notice is marked
   OUTGOING_PENDING. Updates the data store and returns
   an updated notification object upon success and undef
   on failure.

sendNotice ($notice)

   Attempts to send a notice using the appropriate transport
   found in the transport attribute of the notification object.

getNoticeResponse ($notice)

   Attempts to receive a response to a notification over
   the transport found in the transport attribute of the
   notification object.

TRANSPORT INTERFACE

All transport modules must implement the following methods:

  send ($notice)

     Attempts to send a notification object through the
     implemented transport. Returns 1 if successful and
     undef otherwise.

  receive ($notice)

     Attempts to obtain a response for a given
     notification through the implemented transport.
     Returns the message string is successful or undef
     otherwise.

AUTHOR

Michael Gilfix <mgilfix@eecs.tufts.edu> Copyright (C) 2001

SEE ALSO

perl(1), Notify::Notice, Notify::Email

VERSION

This software is currently alpha, version 0.0.1.