beginnings of a Camel white paper

svn path=/trunk/; revision=1971

4 files changed, 544 insertions, 0 deletions

diff --git a/doc/white-papers/mail/ChangeLog b/doc/white-papers/mail/ChangeLog
new file mode 100644
index 0000000000..93bc1fd755
--- /dev/null
+++ b/doc/white-papers/mail/ChangeLog
@@ -0,0 +1,4 @@
+2000-02-28  Dan Winship  <danw@helixcode.com>
+
+	* camel.sgml: Beginnings of a Camel white paper
+
diff --git a/doc/white-papers/mail/camel.sgml b/doc/white-papers/mail/camel.sgml
new file mode 100644
index 0000000000..c3471059b1
--- /dev/null
+++ b/doc/white-papers/mail/camel.sgml
@@ -0,0 +1,268 @@
+<!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>
+    </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 not an acronym; it refers to the fact that the
+      library is capable of going several days without food or water.
+    </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>
+  </sect1>
+
+  <sect1 id="overview">
+    <title>Overview</title>
+
+    <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>
+
+    <para>
+      XXX
+    </para>
+
+    <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>
+
+      <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 and tell me if you think it works.
+
+	  -- Dan
+
+	  --sFSenbAFDSgDfg
+	  Content-Type: text/html
+
+	  Hey, Matt&lt;br&gt;
+	  &lt;br&gt;
+	  Check out this graphic and tell me if you think it works.&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>
+
+</article>
diff --git a/help/white-papers/mail/ChangeLog b/help/white-papers/mail/ChangeLog
new file mode 100644
index 0000000000..93bc1fd755
--- /dev/null
+++ b/help/white-papers/mail/ChangeLog
@@ -0,0 +1,4 @@
+2000-02-28  Dan Winship  <danw@helixcode.com>
+
+	* camel.sgml: Beginnings of a Camel white paper
+
diff --git a/help/white-papers/mail/camel.sgml b/help/white-papers/mail/camel.sgml
new file mode 100644
index 0000000000..c3471059b1
--- /dev/null
+++ b/help/white-papers/mail/camel.sgml
@@ -0,0 +1,268 @@
+<!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>
+    </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 not an acronym; it refers to the fact that the
+      library is capable of going several days without food or water.
+    </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>
+  </sect1>
+
+  <sect1 id="overview">
+    <title>Overview</title>
+
+    <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>
+
+    <para>
+      XXX
+    </para>
+
+    <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>
+
+      <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 and tell me if you think it works.
+
+	  -- Dan
+
+	  --sFSenbAFDSgDfg
+	  Content-Type: text/html
+
+	  Hey, Matt&lt;br&gt;
+	  &lt;br&gt;
+	  Check out this graphic and tell me if you think it works.&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>
+
+</article>