RELEASE_2_1_13/src/blocks/mail/samples/mail/docs/mid-col-2/mail-action.xml - cocoon - Git at Google

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