# MailAction in Cocoon

0.9
Technical document

This document describes the MailAcion of Cocoon.

MailAction

NAME | mail
WHAT | The `MailAction` component is used for creating javamail objects, and putting them into the request attribute map.
TYPE | Action, Sitemap Component
BLOCK | Scratchpad/Block-Mail
CLASS | org.apache.cocoon.mail.MailAction
SINCE | Cocoon 2.1
CACHEABLE | not applicable

Description

The `MailAction` is the central for triggering the creation of javamail objects. Javamail objects as they are created are put into the request attribute map.

Moreover `MailAction` maintains an http-session, and putting into the http-session the `mail-context` of a mail session.

Usage

Use the `MailAction` in case of accessing information accessible via IMAP, or more general accessible via an registed javamail provider.

Sitemap pipeline examples

Setting up the MailAction requires configuring the mail session. The parameter `store-urlname` identifies the store which should be used. The snippet below spefies using the protocol `imap`, and using the imap server host `imap-server-host-name`.
Moreover the request parameters `mail-userid`, and `mail-passwd` replaces the placeholders `''mail-userid''`, and `''mail-passwd''`

Finally as the javamail Session class accepts properties, for configuration purpose, the snippet below switches off the session debugging explicitly. Parameter names having prefix `javax.mail.Session.props:` are put into the javamail session properties map, stripping off the prefix first..

    <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>

Sitemap component configuration example

The `MailAction` has no specific configuration possibilities.

    <map:actions...
      <map:action name="mail"
        src="org.apache.cocoon.mail.Action"
        logger="sitemap.action.mail"
      />
    ...

Configuration

The `MailAction` has no specific configuration possibilities.

Setup

Setting up the MailAction specifies the javamail Session to use, and principal javamail Store to use.

Effect on Object Model and Sitemap Parameters

Request Attribute Objects

As noted above `MailAction` puts XMLizable javamail objects into the request attribute map. The following table lists the request attribute names, set by `MailAction`.

Request Attribues Set By MailAction
Request Attribute Name | Comment
--- | ---
folder | A single folder
folders | Multiple folders
message | A single message
messages | Multiple messages
mail-current-working-folder | The current working folder name
mail-current-working-command | The command processded by MailAction

Each command generates zero, one, or more javamail objects, which are wrapped to become XMLizable, and put into the request attribute map.

MailAction Commands

The `MailAction` supports following commands

List Of MailAction commands
Command | Class
--- | ---
cat-folder | MailCommandManager.MailFolderCatCommand
refresh-folder | MailCommandManager.MailRefreshFolderCommand
list-folder | MailCommandManager.MailListFolderCommand
list-folder-messages | MailCommandManager.MailListMessagesCommand
search-folder-messages | MailCommandManager.MailSearchMessagesCommand
cat-message-by-id | MailCommandManager.MailCatMessageByIdCommand
cat-message-by-uid | MailCommandManager.MailCatMessageByUIDCommand
cat-attachment-of-message-by-id | MailCommandManager.MailCatAttachmentMessageByIdCommand

The following sections describe each of the commands above.

MailFolderCatCommand

This command cats information about a folder

MailFolderCatCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername

MailRefreshFolderCommand

This command closes, and opens a folder, as a side effects new messages of a folder are read.

MailRefreshFolderCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername

MailListFolderCommand

This command list all subfolders of a folder.

MailListFolderCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername
folder-pattern | optional | Speficies the folder-pattern to use, see javamail documentation for allowed wildcards, by default the folder-pattern '%' is used.

MailListMessagesCommand

This command lists all messages of a folder. This command does not requests the mail content, only the mail header information is prefetched.

MailListMessagesCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername

MailSearchMessagesCommand

This command searches for messages. It uses the javamail `SearchTerm` for searching, and it searches only in Subject, and From fields of each message. It uses `SubjectTerm`, and `FromStringTerm` for searching. See the javamail documentation for `SearchTerm` details.

MailSearchMessagesCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername
search | optional | Speficies the search string, by default it has the value of an empty string, matching all messages.

MailCatMessageByIdCommand

This command cats information about a message. The message is specified by it message id. This command requests the content of a message.

MailCatMessageByIdCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername
id | mandatory | Speficies the msgid integer value

MailCatMessageByUIDCommand

This command cats information about a message. The message is specified by it message id. This command requests the content of a message.

MailCatMessageByUIDCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername
uid | mandatory | Speficies the uid of a message

MailCatAttachmentMessageByIdCommand paramters

This command cats an attachment of a mail.

MailCatMessageByIdCommand parameters
Parametername | Mode | Comment
--- | --- | ---
folder | optional | Speficies the foldername
id | mandatory | Speficies the msgid integer value
part-id | mandatory | Speficies the id of the requested mail part.

Marshalling Javamail Objects

As `MailAction` puts XMLizable javamail objects like `javax.mail.Folder`, `javax.mail.Message` into the request attribute map, the following sections describe the xml document structure of these objects

Bugs/Caveats

The `MailAction` is still work in progress. The http-session handling, and the javamail session handling is not stable under every cirumstances.

History

01-04-03: initial creation

See also

As `MailAction` relies on the javamail package, read more about javamail.