| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd"> |
| |
| <document> |
| <header> |
| <title>MailAction in Cocoon</title> |
| <version>0.9</version> |
| <type>Technical document</type> |
| <authors> |
| <person name="Bernhard Huber" email="huber.at.apache.org"/> |
| </authors> |
| <abstract>This document describes the MailAcion of Cocoon.</abstract> |
| </header> |
| <body> |
| <s1 title="MailAction"> |
| <table> |
| <tr> |
| <td>NAME</td><td>mail</td> |
| </tr> |
| <tr> |
| <td>WHAT</td><td>The <code>MailAction</code> component is used for |
| creating javamail objects, and putting them into the request attribute map. |
| </td> |
| </tr> |
| <tr> |
| <td>TYPE</td><td>Action, Sitemap Component</td> |
| </tr> |
| <tr> |
| <!-- choose Core, the block name, or Scratchpad |
| depending on where MailAction sources live |
| --> |
| <td>BLOCK</td><td>Scratchpad/Block-Mail</td> |
| </tr> |
| <tr> |
| <td>CLASS</td><td>org.apache.cocoon.mail.MailAction</td> |
| </tr> |
| <!-- uncomment folling tr iff MailAction is deprecated --> |
| <!--tr> |
| <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td> |
| </tr--> |
| <tr> |
| <td>SINCE</td><td>Cocoon 2.1</td> |
| </tr> |
| <tr> |
| <td>CACHEABLE</td><td>not applicable</td> |
| </tr> |
| </table> |
| </s1> |
| <s1 title="Description"> |
| <p> |
| The <code>MailAction</code> is the central for triggering the creation of javamail objects. |
| Javamail objects as they are created are put into the request attribute map. |
| </p> |
| <p> |
| Moreover <code>MailAction</code> maintains an http-session, and putting into the |
| http-session the <code>mail-context</code> of a mail session. |
| </p> |
| </s1> |
| <s1 title="Usage"> |
| <p> |
| Use the <code>MailAction</code> in case of accessing information accessible via |
| IMAP, or more general accessible via an registed javamail provider. |
| </p> |
| <s2 title="Sitemap pipeline examples"> |
| <p> |
| Setting up the MailAction requires configuring the mail session. |
| The parameter <code>store-urlname</code> identifies the store which should be used. |
| The snippet below spefies using the protocol <code>imap</code>, and using the |
| imap server host <code>imap-server-host-name</code>. |
| <br/> |
| Moreover the request parameters <code>mail-userid</code>, and <code>mail-passwd</code> |
| replaces the placeholders <code>''mail-userid''</code>, and <code>''mail-passwd''</code> |
| </p> |
| <p> |
| Finally as the javamail Session class accepts properties, for configuration purpose, |
| the snippet below switches off the session debugging explicitly. |
| Parameter names having prefix <code>javax.mail.Session.props:</code> are put |
| into the javamail session properties map, stripping off the prefix first.. |
| </p> |
| <source><![CDATA[ |
| <map:match pattern="mail/*.html"> |
| <map:action type="mail"> |
| <!-- configure MailAction --> |
| <map:parameter name="store-urlname" |
| value="imap://''mail-userid'':''mail-passwd''@imap-server-host-name/"/> |
| <map:parameter name="javax.mail.Session.props:mail.debug" |
| value="false"/> |
| </map:action> |
| |
| <!-- access javamail objects --> |
| <map:generator type="serverpages" src="docs/{1}.xsp"/> |
| <map:transform src="stylesheets/mail2html.xsl"/> |
| <map:transform type="html"/> |
| </map:match> |
| ]]></source> |
| </s2> |
| |
| <s2 title="Sitemap component configuration example"> |
| <p> |
| The <code>MailAction</code> has no specific configuration possibilities. |
| </p> |
| <source><![CDATA[ |
| <map:actions... |
| <map:action name="mail" |
| src="org.apache.cocoon.mail.Action" |
| logger="sitemap.action.mail" |
| /> |
| ... |
| ]]></source> |
| </s2> |
| <s2 title="Configuration"> |
| <p> |
| The <code>MailAction</code> has no specific configuration possibilities. |
| </p> |
| </s2> |
| <s2 title="Setup"> |
| <p> |
| Setting up the MailAction specifies the javamail Session to use, and |
| principal javamail Store to use. |
| </p> |
| </s2> |
| |
| <s2 title="Effect on Object Model and Sitemap Parameters"> |
| <p> |
| |
| </p> |
| |
| </s2> |
| <s2 title="Request Attribute Objects"> |
| <p> |
| As noted above <code>MailAction</code> puts XMLizable javamail objects |
| into the request attribute map. The following table lists the request attribute |
| names, set by <code>MailAction</code>. |
| </p> |
| <table> |
| <caption>Request Attribues Set By MailAction</caption> |
| <tr><th>Request Attribute Name</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>A single folder</td></tr> |
| <tr><td>folders</td><td>Multiple folders</td></tr> |
| <tr><td>message</td><td>A single message</td></tr> |
| <tr><td>messages</td><td>Multiple messages</td></tr> |
| <tr><td>mail-current-working-folder</td><td>The current working folder name</td></tr> |
| <tr><td>mail-current-working-command</td><td>The command processded by MailAction</td></tr> |
| </table> |
| <p> |
| Each command generates zero, one, or more javamail objects, which are wrapped |
| to become XMLizable, and put into the request attribute map. |
| </p> |
| </s2> |
| </s1> |
| <s1 title="MailAction Commands"> |
| <p> |
| The <code>MailAction</code> supports following commands |
| </p> |
| <table> |
| <caption>List Of MailAction commands</caption> |
| <tr><th>Command</th><th>Class</th></tr> |
| <tr><td>cat-folder</td><td>MailCommandManager.MailFolderCatCommand</td></tr> |
| <tr><td>refresh-folder</td><td>MailCommandManager.MailRefreshFolderCommand</td></tr> |
| <tr><td>list-folder</td><td>MailCommandManager.MailListFolderCommand</td></tr> |
| <tr><td>list-folder-messages</td><td>MailCommandManager.MailListMessagesCommand</td></tr> |
| <tr><td>search-folder-messages</td><td>MailCommandManager.MailSearchMessagesCommand</td></tr> |
| <tr><td>cat-message-by-id</td><td>MailCommandManager.MailCatMessageByIdCommand</td></tr> |
| <tr><td>cat-message-by-uid</td><td>MailCommandManager.MailCatMessageByUIDCommand</td></tr> |
| <tr><td>cat-attachment-of-message-by-id</td><td>MailCommandManager.MailCatAttachmentMessageByIdCommand</td></tr> |
| </table> |
| |
| <p> |
| The following sections describe each of the commands above. |
| </p> |
| <s2 title="MailFolderCatCommand"> |
| <p> |
| This command cats information about a folder |
| </p> |
| <table> |
| <caption>MailFolderCatCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| </table> |
| </s2> |
| <!-- begin of description of commands --> |
| <s2 title="MailRefreshFolderCommand"> |
| <p> |
| This command closes, and opens a folder, as a side effects new messages of a folder |
| are read. |
| </p> |
| <table> |
| <caption>MailRefreshFolderCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| </table> |
| </s2> |
| <s2 title="MailListFolderCommand"> |
| <p> |
| This command list all subfolders of a folder. |
| </p> |
| <table> |
| <caption>MailListFolderCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| <tr><td>folder-pattern</td><td>optional</td><td>Speficies the folder-pattern to use, |
| see javamail documentation for allowed wildcards, by default the folder-pattern '%' is used. |
| </td> |
| </tr> |
| </table> |
| </s2> |
| <s2 title="MailListMessagesCommand"> |
| <p> |
| This command lists all messages of a folder. This command does not requests |
| the mail content, only the mail header information is prefetched. |
| </p> |
| <table> |
| <caption>MailListMessagesCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| </table> |
| </s2> |
| <s2 title="MailSearchMessagesCommand"> |
| <p> |
| This command searches for messages. It uses the javamail <code>SearchTerm</code> |
| for searching, and it searches only in Subject, and From fields of each message. |
| It uses <code>SubjectTerm</code>, and <code>FromStringTerm</code> for searching. |
| See the javamail documentation for <code>SearchTerm</code> details. |
| </p> |
| <table> |
| <caption>MailSearchMessagesCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| <tr><td>search</td><td>optional</td><td>Speficies the search string, by default it has the |
| value of an empty string, matching all messages.</td> |
| </tr> |
| </table> |
| </s2> |
| <s2 title="MailCatMessageByIdCommand"> |
| <p> |
| This command cats information about a message. The message is specified by |
| it message id. This command requests the content of a message. |
| </p> |
| <table> |
| <caption>MailCatMessageByIdCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| <tr><td>id</td><td>mandatory</td><td>Speficies the msgid integer value</td></tr> |
| </table> |
| </s2> |
| <s2 title="MailCatMessageByUIDCommand"> |
| <p> |
| This command cats information about a message. The message is specified by |
| it message id. This command requests the content of a message. |
| </p> |
| <table> |
| <caption>MailCatMessageByUIDCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| <tr><td>uid</td><td>mandatory</td><td>Speficies the uid of a message</td></tr> |
| </table> |
| </s2> |
| <s2 title="MailCatAttachmentMessageByIdCommand paramters"> |
| <p> |
| This command cats an attachment of a mail. |
| </p> |
| <table> |
| <caption>MailCatMessageByIdCommand parameters</caption> |
| <tr><th>Parametername</th><th>Mode</th><th>Comment</th></tr> |
| <tr><td>folder</td><td>optional</td><td>Speficies the foldername</td></tr> |
| <tr><td>id</td><td>mandatory</td><td>Speficies the msgid integer value</td></tr> |
| <tr><td>part-id</td><td>mandatory</td><td>Speficies the id of the requested mail part.</td></tr> |
| </table> |
| </s2> |
| |
| <!-- end of description of commands --> |
| |
| </s1> |
| <s1 title="Marshalling Javamail Objects"> |
| <p> |
| As <code>MailAction</code> puts XMLizable javamail objects like |
| <code>javax.mail.Folder</code>, <code>javax.mail.Message</code> into the request |
| attribute map, the following sections describe the xml document structure of |
| these objects |
| </p> |
| </s1> |
| |
| <s1 title="Bugs/Caveats"> |
| <p> |
| The <code>MailAction</code> is still work in progress. |
| The http-session handling, and the javamail session handling is not stable |
| under every cirumstances. |
| </p> |
| </s1> |
| <s1 title="History"> |
| <p> |
| 01-04-03: initial creation |
| </p> |
| </s1> |
| <s1 title="Copyright"> |
| <p> |
| Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved. |
| </p> |
| </s1> |
| <s1 title="See also"> |
| <p> |
| As <code>MailAction</code> relies on the javamail package, read more about |
| <link href="http://java.sun.com/products/javamail/index.html">javamail</link>. |
| </p> |
| <p> |
| </p> |
| </s1> |
| </body> |
| </document> |
| |
