NAME

Mail::Box-Overview - objects used by Mail::Box

DESCRIPTION

The Mail::Box package is a suite of classes for accessing and managing email folders in a folder-independent manner. This package is an alternative to the Mail::Folder and MIME::* packages. It abstracts the details of messages, message storage, and message threads, while providing better performance than older mail packages. It is meant to provide an object-oriented toolset for all kinds of e-mail applications, under which Mail User-Agents (MUA) and mail filtering programs.

This package is modular --parts of it can be used independently of the rest. For example, the Mail::Box::Manager can automatically determine that a folder is in Mbox format and return an object of the Mail::Box::Mbox class, or the user program can bypass the manager and create Mail::Box::Mbox objects directly. Similarly, if the user program is only manipulating a single message, a Mail::Message.

The Mail::Box package has special features to help MUA's access folder data quickly in random order. You will not really benevit (neither slower) if you need the full folder sequencially.

This code is beta, which means that there are no serious applications written with it yet. Please inform the author when you have, so this module can be marked as stable. Read the STATUS file enclosed in the package for more details. You may also want to have a look at the sample scripts in the scripts directory.

Overview of the Mail::Box Package

                       <has-a>      Mail::Box::Mbox
  Mail::Box::Manager <---------*    (Mail::Box::Dir::MH)
         ^                :         (Mail::Box::Dir::Maildir)
         |           (maintains)
         |                :
         `---------------------*  Mail::Box::Thread::Manager
                      (<has-a>)



  Mail::Box::Mbox  <-----------* Mail::Box::Mbox::Message
         ^             <has-a>            ^
         | <isa>                          | <isa>
         |                                |
     Mail::Box     ............. Mail::Box::Message
                                          ^
                                          | <isa>
                                          |
                                    Mail::Message
                                         / \
                                       <has-a>  
                                       /     \
                            Mail::Message   Mail::Message 
                              ::Body            ::Head

The situation for MH and Maildir folders is a little more complicated, because they have an extra intermediate level: Mail::Box::Dir. In the future, when more Mbox-like folder types get implemented, there may be a Mail::Box::File level too. The following is also true for the mail boxes

   Mail::Box         Mail::Box
 ::MH::Message   ::Maildir::Message
          \         /
           \       /
           Mail::Box         Mail::Box
        ::Dir::Message    ::Mbox::Message
                  \         /
                   \       /
                   Mail::Box
                   ::Message
                       |
                       |
                 Mail::Message

The classes and relationships are described as follows:

Mail::Box::Manager

The mailbox manager encapsulates folder management issues. It maintains a set of open mail folders (mailboxes), and provides methods for opening and closing them, efficiently moving messages between folders, and efficiently appending messages to folders. It contains Mail::Box objects which may be of different types. Most folder types can be detected automatically.

The main manager also manages message-thread detector objects, and informs them when the contents of a folder have changed. This manager class is the only one you instantiate yourself: objects of all other classes will be provided by your folder manager.

You are strongly advised to use this object, but you can often do without it and open a specific folder-type yourself.

Mail::Message

A base class that defines an interface for manipulating the head and body of a message. There are various header-objects (see Mail::Message::Head) and a bunch of body objects (Mail::Message::Body).

The Mail::Message::Construct package is loaded when more complex tasks have to be performed on messages, like reply or forward. These functionalities are descibed and implemented in the ::Construct file, but are added to the Mail::Message namespace when used.

Message types which are foreign to Mail::Box can be used in the Mail::Box environment: there are some convertors implemented via Mail::Message::Convert. Particulary the popular Mail::Internet and MIME::Entity are supported.

Mail::Box::Message

An abstract base class which defines an interface for mail messages which are stored in any folder. It inherits from Mail::Message, and adds the basic idea of location to it.

Mail::Box

A base class that defines a standard interface for mail boxes which is independent of mailbox type. Objects of this class contain a Mail::Box::Locker and a list of Mail::Box::Message objects.

Mail::Box::Mbox

This class derives from Mail::Box, and implements its interface for mbox-style folders. It maintains a set of Mail::Box::Mbox::Message objects, which are derived from a Mail::Box::Message.

Mbox-style folders have one file containing multiple messages per folder. When folders get large, access tends to get slow.

Mail::Box::Dir

The base class for all folders which use a directory organization: each message is a separate entity (file) grouped in a directory. Each Mail::Box::Dir::Message represents one message, one such entity.

Mail::Box::MH

This class derives from Mail::Box::Dir, and implements its interface for MH-style folders. It maintains a set of Mail::Box::MH::Message objects, which are derived from a Mail::Box::Dir::Message.

MH-style folders are represented by a directory, where each message is stored in a seperate file. The message files are sequentially numbered. It is fast to open one single message, but hard to get an overview.

Mail::Box::MH:Index

The base class for MH mailbox indexes which provides methods for reading, writing, and managing message indexes. These indexes are used to speed-up access to directory based folders.

Mail::Box::MH::Labels

Also for efficiency reasons, a separate file is maintained which contains flags about the messages. This file for instance lists new files. This way, the MH message files do not have to be opened to find that out.

Mail::Box::Maildir

As the MH folder type, this class derives from Mail::Box::Dir. It implements its interface for Maildir-style folders. It maintains a set of Mail::Box::Maildir::Message objects, which are derived from a Mail::Box::Dir::Message.

Mail::Message::Body

This is the base-class for all message-bodies. It describes what you can do with any kind of body. The body-types differ on the way how the keep the body-content during the run of your program.

One special case of the body-types is the ::Multipart, which contains a set of Mail::Message::Part objects. These are just like normal messages, except that they are contained in an other message.

When needed, the functionality of the body objects is extended with ::Body::Construct and ::Body::Encode. The former package implements things like concatenation. The later controls message encoding and decoding. In the current implementation this is limited to transfer encodings (implemented in the Mail::Message::TransferEnc packages), Character and mime recodings are on the wish-list.

Mail::Message::Head

The header for a single message. Maintains a set of Mail::Message::Field objects, each containing one header line. Header fields are the only objects which have no logging and tracing facilities, purely for reasons of performance.

The header object has three sub-classes: the ::Complete version knows all lines for sure, ::Subset maintains an unknown subset of lines, and the ::Delayed has no lines yet but knows where to get them.

The latter two will automatically get the missing header lines from the mailbox files when needed, and so transform into a ::Complete header. It is fully transparent to the user of Mail::Box in which shape the header really is on the moment.

Mail::Box::Thread::Manager

Maintains a set of message-threads over one or more folders. A message-tread is a start message with all the replies on it. And the replies on replies, and so on. This object is used to construct the thread for a set of open folders.

This object maintains linked lists of Mail::Box::Thread::Node objects. Mail::Box::Message::Dummys fill-up some holes.

Mail::Box::Locker

Provides a folder locking interface which is inherited by the Mail::Box class. Currently it supports dot-file locking (filename.lock), flock filehandle locking, and locking over NFS. Each is implemented in a separate class. A multi-locker, using a set of lock-methods at the same time is also available.

Mail::Box::Search

The set of search packages implement various search techniques in an uniformal way. Although implementing your own search algorithm is simple in general, in practice multiparts, encodings, and mime-types complicate things.

Mail::Box::Parser

Describes the interface to the two current folder parsers: the parser implemented with Inline::C, and the parser fully in written in Perl. The first is faster, the second more portable.

Mail::Box::Tie

Provides hash (::HASH) or array tied (::ARRAY) access to any mail folder derived from Mail::Box. This beautifies your code in some applications.

Mail::Reporter

A debugging and logging class which is inherited by most of the Mail::* modules. For each object, you can say what log and error reports must be kept or directly presented to the user. This way you can decide to have Mail::Box report about problems, or do it all yourself.

All classes are written to be extendable.

SEE ALSO

Mail::Box-Cookbook

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version $version.

Copyright (c) 2001 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.