path: root/doc/white-papers/mail/camel.sgml

<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity Evolution "<application>Evolution</application>">
<!entity Camel "Camel">
]>

<article class="whitepaper" id="camel">

  <artheader>
    <title>The &Camel; Messaging Library</title>

    <authorgroup>
      <author>
    <firstname>Dan</firstname>
    <surname>Winship</surname>
    <affiliation>
      <address>
        <email>danw@helixcode.com</email>
      </address>
    </affiliation>
      </author>

      <author>
    <firstname>Bertrand</firstname>
    <surname>Guiheneuf</surname>
    <affiliation>
      <address>
        <email>bertrand@helixcode.com</email>
      </address>
    </affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2000</year>
      <holder>Helix Code, Inc.</holder>
    </copyright>

  </artheader>

  <sect1 id="introduction">
    <title>Introduction</title>

    <para>
      &Camel; is a generic messaging library. It is being used as the
      back end for the mail component of &Evolution;. The name
      "&Camel;" is an acronym; it refers to the fact that the
      library is capable of going several days without food or water.
      It means : Camel has an Acronym that Makes Everyone Laugh.
    </para>

    <para>
      &Camel;'s initial design is heavily based on Sun's
      <trademark>JavaMail</trademark> API. It uses the Gtk+ object
      system, and many of its classes are direct analags of JavaMail
      classes. Its design has also been influenced by the features of
      IMAP, and the limitations of the standard UNIX mbox mail store,
      which set some of the boundaries on its requirements and
      extensibility.
    </para>

    <para>
      &Camel; sees all message repositories as stores containing
      folders. These folders in turn contain the messages the client
      actually accesses. The use of such a unified interface allows
      the client applications to be very extensible. &Camel; includes
      an external provider mechanism which allows applications to
      dynamically load and use protocols which were not available when
      the application was initially written.
    </para>

    <para>
      The abstract store/folder mechanism is a powerful and versatile
      way of accessing messages. No particular asumptions are made on
      the client side, thus allowing new ways of managing the
      messages. For example, the messages stored in the folders don't
      necessarily have to share some common physical location. The
      folder can be a purely virtual folder, containing only
      references to the actual messages. This is used by the "vFolder"
      provider, which allows you select messages meeting particular
      criteria and deal with them as a group.
    </para>

    <para>
      In addition to these possibilities, &Camel; has full MIME
      support. &Camel; MIME messages are lightweight objects
      representing the MIME skeleton of the actual message. The data
      contained in the subparts are never stored in memory except when
      they are actually needed. The application, when accessing the
      various MIME objects contained in the message (text parts,
      attachments, embedded binary objects ...) asks &Camel; for a
      stream that it can read data from. This scheme is particularly
      useful with the IMAP provider. IMAP has strong MIME support
      built-in, which allows &Camel; to download only the parts of
      messages that it actually needs: attachments need not be
      downloaded until they are viewed, and unnecessary
      "multipart/alternative" parts will never be read off the server.
    </para>
  </sect1>

  <sect1 id="overview">
    <title>Overview</title>

    <graphic format="gif" fileref="camel"></graphic>

    <para>
      To begin using &Camel;, an application first creates a
      <classname>CamelSession</classname> object. This object is used
      to store application defaults, and to coordinate communication
      between providers and the application.
    </para>

    <para>
      A <classname>CamelProvider</classname> is a dynamically-loadable
      module that provides functionality associated with a specific
      service. Examples of providers are IMAP and SMTP. Providers
      include subclasses of the various other &Camel; classes for
      accessing and manipulating messages.
    </para>

    <para>
      <classname>CamelService</classname> is an abstract class for
      describing a connection to a local or remote service. It
      currently has two subclasses: <classname>CamelStore</classname>,
      for services that store messages (such as IMAP servers and mbox
      files), and <classname>CamelTransport</classname>, for services
      that deliver messages (such as SMTP, or a local MTA). A provider
      could also be both a store and a transport, as in the case of
      NNTP.
    </para>

    <para>
      A <classname>CamelStore</classname> contains some number of
      <classname>CamelFolder</classname> objects, which in turn
      contain messages. A <classname>CamelFolder</classname> provides
      a <classname>CamelFolderSummary</classname> object, which
      includes details about the subject, date, and sender of each
      message in the folder. The folder also includes the messages
      themselves, as subclasses of <classname>CamelMedium</classname>.
    </para>

    <para>
      Email messages are represented by the
      <classname>CamelMimeMessage</classname> class, a subclass of
      <classname>CamelMedium</classname>. This class includes
      operations for accessing RFC822 and MIME headers, accessing
      subparts of MIME messages, encoding and decoding Base64 and
      Quoted-Printable, etc.
    </para>

    <para>
      <classname>CamelTransport</classname> includes methods for
      delivering messages. While the abstract
      <function>CamelTransport::send</function> method takes a
      <classname>CamelMedium</classname>, its subclasses may only be
      able to deliver messages of specific
      <classname>CamelMedium</classname> subclasses. For instance,
      <classname>CamelSendmailTransport</classname> requires a
      <classname>CamelMimeMessage</classname>, because it needs a
      message that includes a "To:" header. A hypothetical
      <classname>CamelNNTPTransport</classname> would need a
      <classname>CamelNewsMessage</classname>, which would have a
      "Newsgroups:" header.
    </para>

    <para>
      The content of messages are referred to using
      <classname>CamelStream</classname> and its subclasses. In the
      case of an mbox-based store, the
      <classname>CamelStream</classname> would abstract the operation
      of reading the correct section of the mbox file. For IMAP,
      reading off the <classname>CamelStream</classname> might result
      in commands being issued to the remote IMAP server and data
      being read off a socket.
    </para>

    <para>
      The final major class in &Camel; is
      <classname>CamelException</classname>, which is used to
      propagate information about errors. Many methods take a
      <classname>CamelException</classname> as an argument, which the
      caller can then check if an error occurs. It includes both a
      numeric error code which can be interpreted by the program, and
      a text error message that can be displayed to the user.
    </para>
  </sect1>

  <sect1 id="classes">
    <title>Major Subcomponents</title>

    <sect2 id="store">
      <title>The Message Store</title>

      <para>
        A <classname>CamelStore</classname> inherits the ability to
        connect and authenticate to a service from its parent class,
        <classname>CamelService</classname>. It then adds the ability
        to retrieve folders. A store must contain at least one folder,
        which can be retrieved with
        <function>CamelStore::get_default_folder</function>. There are
        also methods to retrieve the "top-level" folder (for
        hieararchical stores), and to retrieve an arbitrary folder by
        name.
      </para>

      <para>
        All <classname>CamelFolder</classname>s must implement certain
        core operations, most notably generating a summary and
        retrieving and deleting messages. A
        <classname>CamelFolder</classname> must assign a permanently
        unique identifier to each message it contains. Messages can
        then be retrieved via
        <function>CamelFolder::get_message_by_uid</function>. Alternately,
        within a single mail-reading session, messages can be referred
        to by their linear position within the store using
        <function>CamelFolder::get_message_by_number</function>.
      </para>

      <para>
        Folders must also implement the
        <function>get_parent_folder</function> and
        <function>list_subfolders</function> methods. For stores that
        don't allow multiple folders, they would return NULL and an
        empty list, respectively. Stores that do allow multiple
        folders will also define methods for creating and deleting
        folders, and for moving messages between them (assuming the
        folders are writable).
      </para>

      <para>
        Folders that support searching can define the
        <function>search_by_expression</function> method. For mbox
        folders, this is implemented by indexing the messages with the
        ibex library and using that to search them later. For IMAP
        folders, this uses the IMAP SEARCH command. Other folder types
        might not be able to implement this functionality, in which
        case users would not be able to do full-content searches on
        them.
      </para>
    </sect2>

    <sect2 id="messages">
      <title>Messages</title>

      <para>
        As mentioned before, messages are represented by subclasses of
        <classname>CamelMedium</classname>.
        <classname>CamelMedium</classname> itself is a subclass of
        <classname>CamelDataWrapper</classname>, a generic class for
        connecting a typed data source to a data sink.
        <classname>CamelMedium</classname> adds the concept of message
        headers versus message body.
        (<classname>CamelDataWrapper</classname> has one other
        important subclass, <classname>CamelMultipart</classname>,
        which is used to provide separate access to the multiple
        independent parts of a multipart MIME type.)
        <classname>CamelMedium</classname>'s subclasses provide more
        specialized handling of various headers:
        <classname>CamelMimePart</classname> adds special handling for
        the &ldquot;Content-*&rdquot; headers in MIME messages, and
        its subclass <classname>CamelMimeMessage</classname> adds
        handling for the RFC822 headers.
      </para>

      <graphic format="gif" fileref="mimemessage"></graphic>

      <para>
        Consider a message with two parts: a text part (in both plain
        text and HTML), and an attached image:

    <programlisting>

      From: Dan Winship &lt;danw@helixcode.com&gt;
      To: Matt Loper &lt;matt@helixcode.com&gt;
      Subject: the Camel white paper
      MIME-Version: 1.0
      Content-Type: multipart/mixed;
        boundary="jhTYrnsRrdhDFGa"

      This is a multi-part message in MIME format.
      --jhTYrnsRrdhDFGa
      Content-Type: multipart/alternative;
        boundary="sFSenbAFDSgDfg"

      --sFSenbAFDSgDfg
      Content-Type: text/plain

      Hey, Matt

      Check out this graphic...

      -- Dan

      --sFSenbAFDSgDfg
      Content-Type: text/html

      Hey, Matt&lt;br&gt;
      &lt;br&gt;
      Check out this graphic...&lt;br&gt;
      &lt;br&gt;
      -- Dan&lt;br&gt;
      &lt;br&gt;
      --sFSenbAFDSgDfg--

      --jhTYrnsRrdhDFGa
      Content-Type: image/png
      Content-Transfer-Encoding: base64

      F4JLw0ORrkRa8AwAMQJLAaI3UDIGsco9RAaB92...
      --jhTYrnsRrdhDFGa--
    </programlisting>

    <para>
      In &Camel;, this would be represented as follows:
    </para>

        <graphic fileref="samplemsg"></graphic>
      </sect2>

      <sect2 id="streams">
        <title>Streams</title>

    <para>
      Streams are a generic data transport layer. Two basic stream
      classes are <classname>CamelStreamFs</classname>, for
      reading and writing files, and
      <classname>CamelStreamMem</classname>, for reading from and
      writing to objects that are already in memory.
    </para>

    <para>
      Streams can also be chained together. So a CamelMimePart
      containing base64-encoded data can filter its output through
      a CamelStreamB64. Other parts of the application that want
      to read its data will never need to even realize that the
      original data was encoded.
    </para>
      </sect2>

</article>