diff options
| -rw-r--r-- | doc/white-papers/mail/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/white-papers/mail/camel.sgml | 268 | ||||
| -rw-r--r-- | help/white-papers/mail/ChangeLog | 4 | ||||
| -rw-r--r-- | help/white-papers/mail/camel.sgml | 268 |
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 <danw@helixcode.com> + To: Matt Loper <matt@helixcode.com> + 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<br> + <br> + Check out this graphic and tell me if you think it works.<br> + <br> + -- Dan<br> + <br> + --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 <danw@helixcode.com> + To: Matt Loper <matt@helixcode.com> + 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<br> + <br> + Check out this graphic and tell me if you think it works.<br> + <br> + -- Dan<br> + <br> + --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> |