The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-App-Mercury-0.80
River stage zero No dependents
++
/ Apache::App::Mercury

NAME

Apache::App::Mercury - Internal web messaging for Apache mod_perl (1.x)

SYNOPSIS

  # first, edit Apache/App/Mercury/Config.pm and set variables appropriately

  # from the mod_perl handler of your application
  #  Note: in these examples My::MVC::Controller is assumed to be a class
  #    which provides a persistence framework so object variables are kept
  #    across http requests; it also must implement some predefined methods
  #    (see below for details on these methods)
  $controller = My::MVC::Controller->new;
  $controller->handler;
  ...

  # My::MVC::Controller top-level control method (e.g. handler())
  sub handler {
    my $self = my $controller = shift;
    ...
    if ($r->uri eq Apache::App::Mercury::Config::BASE_URI()) {
      $controller->{wm} = Apache::App::Mercury->new
      $controller->{wm}->initialize($controller);
      $controller->{wm}->content_handler;
      $controller->{wm}->cleanup;
    }
    ...
    # $r is an Apache->request object
    $r->content_type("text/html");
    $r->send_http_header;
    $r->print("<HTML><HEAD><TITLE>".$controller->pagetitle."</TITLE></HEAD>".
              "<BODY>".$controller->pagebody."</BODY></HTML>");
  }

  ### === --<>-- === ###

  # to generate a message from 'sender_user' to 'recipient_user' with a
  # security-level setting of 'low' (security => 'low'), and without
  # storing a copy of the message in the sender's Outbox (nocopy => 1)
  Apache::App::Mercury::Message->new
    ({ 'sent_to' => 'recipient_user', 'sender' => 'sender_user',
       'subject' => "Subject line ...", 'nocopy' => 1, 'security' => 'low',
       'body' => "Message body\nline 2\nline 3\n...\n" })
    ->store;

MYTHOLOGY

Mercury the swift messenger of the ancient gods.

The Greek god Hermes (the Roman Mercury) was the god of translators and interpreters. He was the most clever of the Olympian gods, and served as messenger for all the other gods. He ruled over wealth, good fortune, commerce, fertility, and thievery.

Among his personal favorite commercial activities was the corn trade. He was also the god of manual arts and eloquence. As the deity of athletes, he protected gymnasiums and stadiums.

DESCRIPTION

Apache::App::Mercury is a customizable, extensible customer to customer, store and forward messaging application for Apache mod_perl (1.x). It might be useful if you have a web application with many users who login periodically, and you want to give each of them a "message box" in which they can receive auto-generated messages, or communicate with each other. It uses a relational database (accessed via DBI) to store and retrieve messages, and CGI.pm to display them in standard HTML. It closely resembles an MVC design pattern, and it handles all message box navigation, message composition, sending, replying, etc.

INTERACTIONS WITH OTHER CLASSES

Controller class

Apache::App::Mercury expects to be instantiated by a Controller class which provides object persistence features (e.g. with Apache::Session). To do its job, it also expects to have its initialize($ctlr_obj), content_handler(), and cleanup() methods called (in that order).

Apache::App::Mercury keeps a reference to the calling Controller object, (saved by the initialize($ctlr_obj) method call), and expects the Controller object to implement a few predefined accessors. They are:

  • infomsg()

  • pagetitle()

  • pagebody()

  • get_time()

  • sitemark()

For explanations of what these accessors should access, see the Apache::App::Mercury::Controller manpage.

The Controller object is also expected to hold the following instance variables: (And yes, I know this is bad OO-programming practice to not use an accessor, but oh well...)

$controller->{q}

A CGI query object for the current http request.

$controller->{r}

An Apache->request object for the current http request.

Aside from the names and functions of the above five accessors and two instance variables, the controller class has no other restraints. You will likely want to simply add these accessors and variables to an existing class in your application.

Provided in this distribution is the Apache::App::Mercury::Controller class, which is an example (almost usable) Controller class which illustrates how your Controller should interact with Apache::App::Mercury.

Display class

Provided with this distribution is the Apache::App::Mercury::Display class, which implements all view-specific methods for the Apache::App::Mercury application. If you want to change or extend the look, then you can subclass Apache::App::Mercury::Display and add or override its methods.

UserManager class

Apache::App::Mercury needs some way to get information about the user accounts in your application. It does this through a user manager class (which would be part of the data model in an MVC design). Your user manager class should implement the following methods:

  • userprofile()

  • get_userinfo()

  • mailboxes()

  • mail_trans_filter()

  • auto_forward()

For explanations of what these methods should do, see the Apache::App::Mercury::UserManager manpage.

DATABASE SETUP

Currently, Apache::App::Mercury only supports MySQL for its message backing store. Adding support for other databases should be fairly straightforward - I invite anyone to take the initiative of doing it.

You need to create a MySQL database, set the variable Apache::App::Mercury::Config::DBI_CONNECT_STR, and create the following two tables in the database you just created:

 CREATE TABLE messages (
  id          int(10) unsigned DEFAULT '0' NOT NULL auto_increment,
  recipient   varchar(16) DEFAULT '' NOT NULL,
  sent_to     varchar(255) DEFAULT '' NOT NULL,
  sender      varchar(16) DEFAULT '' NOT NULL,
  timestamp   timestamp(14),
  subject     varchar(100),
  body        text,
  attachments text NOT NULL,
  status      enum('unread','read','replied','forwarded','deleted') DEFAULT 'unread',
  status_sender enum('unread','read','replied','forwarded','deleted') DEFAULT 'unread',
  status_smtp enum('unsent','sent','checked') DEFAULT 'unsent' NOT NULL,
  code        varchar(15) DEFAULT '' NOT NULL,
  box         varchar(16) DEFAULT '' NOT NULL,
  trans       enum('hide','show') DEFAULT 'hide' NOT NULL,
  security    enum('low','medium','high') DEFAULT 'medium',
  PRIMARY KEY (id),
  KEY         recipient (recipient),
  KEY         timestamp (timestamp),
  KEY         sender (sender),
  KEY         code (code),
  KEY         box (box),
  KEY         sent_to (sent_to(34)),
  KEY         trans (trans),
  KEY         status_smtp (status_smtp)
 );

 CREATE TABLE message_attachments (
  aid         int(10) unsigned DEFAULT '0' NOT NULL auto_increment,
  filesys     char(255) DEFAULT '' NOT NULL,
  attachment  char(255) DEFAULT '' NOT NULL,
  msg_ids     char(255) DEFAULT '' NOT NULL,
  PRIMARY KEY (aid),
  UNIQUE      filesys (filesys)
 );

ACCESSORS

controller()

Returns the Controller object which was originally set by the initialize($ctrlr_obj) method.

user_manager()

Returns the UserManager object which was instantiated in the initialize() method using Apache::App::Mercury::Config::USER_MANAGER_CLASS.

METHODS

Not yet documented.

BUGS

Maybe a few mosquitos, some spiders, a sweat fly, and an ant colony. In other words, probably many. In particular, the installation procedure might need some work. Feel free to e-mail any problems you encounter while trying to install/configure for your site.

AUTHORS

Adi Fairbank <adi@adiraj.org>

Thanks to Tyler Kendall <tyler@pidgeonenglish.com> for help with implementation of the ancestor version of this software (the concept on which this software is based).

COPYRIGHT

Copyright (c) 2003 - Adi Fairbank

This software (Apache::App::Mercury and all related Perl modules under the Apache::App::Mercury namespace) is copyright Adi Fairbank.

COPYLEFT (LICENSE)

This module is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free Software
     Foundation; either version 1, or (at your option) any later version,

  or

  b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC; if not, the following URL references a copy of it (as of June 8, 2003):

  http://www.perl.com/language/misc/Artistic.html

You should have received a copy of the GNU General Public License along with this program, in the file GPL; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA; or try the following URL which references a copy of it (as of June 8, 2003):

  http://www.fsf.org/licenses/gpl.html

LAST MODIFIED

July 19, 2003