<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!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:generate 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="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>

