Author: berndf
Date: Tue Sep 26 23:36:28 2006
New Revision: 450345
URL: http://svn.apache.org/viewvc?view=rev&rev=450345
Log:
initial documentation (POSTAGE-16, and also POSTAGE-5)
Added:
james/postage/trunk/src/site/xdoc/custom_test_mails.xml
james/postage/trunk/src/site/xdoc/test_mail_format.xml
Modified:
james/postage/trunk/src/site/site.xml
james/postage/trunk/src/site/xdoc/index.xml
james/postage/trunk/src/site/xdoc/prepare_james.xml
Modified: james/postage/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/james/postage/trunk/src/site/site.xml?view=diff&rev=450345&r1=450344&r2=450345
==============================================================================
--- james/postage/trunk/src/site/site.xml (original)
+++ james/postage/trunk/src/site/site.xml Tue Sep 26 23:36:28 2006
@@ -34,7 +34,10 @@
<menu name="Postage">
<item name="Overview" href="index.html"/>
- <item name="Prepare James" href="prepare_james.html"/>
+ <item name="Prepare James" href="prepare_james.html"/>
+ <item name="Test mail format" href="test_mail_format.html"/>
+ <item name="Custom test mails" href="custom_test_mails.html"/>
+
</menu>
${reports}
Added: james/postage/trunk/src/site/xdoc/custom_test_mails.xml
URL:
http://svn.apache.org/viewvc/james/postage/trunk/src/site/xdoc/custom_test_mails.xml?view=auto&rev=450345
==============================================================================
--- james/postage/trunk/src/site/xdoc/custom_test_mails.xml (added)
+++ james/postage/trunk/src/site/xdoc/custom_test_mails.xml Tue Sep 26 23:36:28
2006
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Custom test mails</title>
+ <author email="[email protected]">James Postage Project
Team</author>
+ </properties>
+ <body>
+ <section name="How to run your own test mails">
+ <p>Custom test mails are usefull to test specific configurations or
functionalities of your mail server.</p>
+ <p>Take for example virus checking. You want to make sure that mails
containing a virus are recognized and flagged in the right way.</p>
+ <p>To achieve this, you make Postage generate mock-up virus mails. When
working correctly, the server for example marks those mails by adding a warning
header.
+ Postage picks up the mail and a custom validator checks if the header
is present.</p>
+ <p>At validation time, custom code has access to the complete mail,
including headers and body parts available for validation.</p>
+ <p>Depending on the result, you mark the mail's result record as
valid/invalid making the result appear in the detailed report.</p>
+ </section>
+
+ <section name="Two classes to implement">
+ <p>MailFactory and MailValidator are two interfaces which must be
implemented. Both can be found in package
<code>org.apache.james.postage.mail</code>.</p>
+ <p>MailFactory generates the test mail, MailValidator analyzes the
received mail and
+ checks if it conforms to the expected result, whatever 'result' may
be in the particular use case.</p>
+ </section>
+
+ <section name="MailFactory">
+ <p>To comply with Postage best practices, it is recommended not to
implement MailFactory directly.
+ The most convenient way is to subclass
org.apache.james.postage.mail.AbstractMailFactory.
+ Two methods must be implemented:
+ </p>
+ <p>
+ <source>abstract protected void populateMessage(MimeMessage
message, MailSender mailSender, MailProcessingRecord mailProcessingRecord)
throws MessagingException;</source>
+ </p>
+ <p><code>populateMessage</code> receives an initialized
<code>MimeMessage</code> which is missing only use case specific data.
+ See <code>DefaultMailFactory.java</code> for an example.
+ </p>
+ <p>
+ <source>abstract protected Class
getValidatorClass();</source>
+ </p>
+ <p><code>getValidatorClass</code> must simply return the
validators class object.
+ </p>
+ </section>
+
+ <section name="Adding the factory class to the configuration">
+ <p>Each <code><send></code> element in the Postage configuration
file has an optional attribute, <code>mail-factory-class</code>.
+ It simply receives the fully-qualified class name. Here is an example:
+ <source>
+ <profile name="int-ext" source="intern" target="extern">
+ <send count-per-min="10" subject="int2ext"
+ text-size-min="10" text-size-max="1000" binary-size-min="1"
binary-size-max="1000"
+ <b>mail-factory-class="my.own.custom.TestMailFactory"</b>
+ />
+ </profile>
+ </source>
+ </p>
+ </section>
+
+ <section name="MailValidator">
+ <p>The validator class is responsible for judging whether the resulting
mail matches the expected criteria.
+ The <code>DefaultMailValidator</code> for example checks if binary
and text body parts have the same sizes
+ as when they were originally created by
<code>DefaultMailFactory</code>. </p>
+ <p>Other potential validations include checking headers, added
footers, removed attachments, introspecting mime contents and many more.
+ </p>
+ <p>
+ All validators are required to implement interface
<code>org.apache.james.postage.mail.MailValidator</code>, declaring one
method:<br/>
+ <source>boolean validate(Message message,
MailProcessingRecord record);</source>
+ </p>
+ <p>The MailFactory adds a Postage header to the test email,
specifying which validator class has to be instantiated. If this header is
missing,
+ the validation cannot be invoked.
+ </p>
+
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Modified: james/postage/trunk/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/james/postage/trunk/src/site/xdoc/index.xml?view=diff&rev=450345&r1=450344&r2=450345
==============================================================================
--- james/postage/trunk/src/site/xdoc/index.xml (original)
+++ james/postage/trunk/src/site/xdoc/index.xml Tue Sep 26 23:36:28 2006
@@ -20,33 +20,48 @@
<document>
<properties>
<title>Overview</title>
- <author email="[email protected]">James jSPF Project
Team</author>
+ <author email="[email protected]">James Postage Project
Team</author>
</properties>
<body>
- <section name="Overview">
- <p>Postage is a stand-alone application generating constant mail traffic
on a James server instance. It can be considered being a load test tool.</p>
- <p>Postage records the resources used by James and supports finding
resource leaks, for example memory bottlenecks.</p>
- <p>While putting load on James, Postage also records the resulting mail
traffic and tries to match incoming and outgoing mail making it possible to use
it for end-to-end test.</p>
- <p>It's flexible enough to mimic many real-world load scenarios, for
example</p>
- <ul>
- <li>many users, each receiving few mails every day</li>
- <li>few users, heavily receiving mails</li>
- <li>moderate mail traffic, yet very big attachments</li>
- </ul>
- </section>
- <section name="Features">
- <ul>
- <li>Easy XML-file-based configuration with multiple running scenarios
for different load profiles</li>
- <li>Supports unlimited number of internal and external users.</li>
- <li>Within one scenario supports different email profiles running in
parallel. Every profile has its own specification in terms of</li>
+ <section name="Postage - A Mail-Traffic Generator">
+ <p>Postage is a stand-alone pure-java application generating mail
traffic on mail servers.</p>
+ <p>It uses standard mail protocols to do this, currently POP3 and
SMTP.</p>
+ <p>Therefore, it is well suited for testing any mail server supporting
those protocols.</p>
+ <p>It was particularily created for running against Apache James Server
and contains special feature for it.</p>
+ </section>
+
+ <section name="Load scenarios">
+ <p>Through the easy-to-use XML-file-based configuration, you can specify
exactly the running scenario for your load profile.</p>
+ <p>Supports unlimited number of internal and external users.</p>
+ <p>Is flexible enough to mimic many real-world load scenarios, for
example
+ <ul>
+ <li>many users, each receiving few mails every
day</li>
+ <li>few users, heavily receiving mails</li>
+ <li>moderate mail traffic, yet very big
attachments</li>
+ </ul>
+ </p>
+ <p>Within one scenario, Postage supports different email profiles
running in parallel. Every profile has its own specification in terms of
<ul>
<li>number of generated mails per minute</li>
<li>sender/receiver</li>
- <li>mail size</li>
+ <li>mail size</li>
</ul>
- <li>Records incoming and outgoing mails and matches them to keep track
of successful and failed deliveries</li>
- <li>Is able to record the Mail Servers thread and heap memory
consumption (only Java SE 5)</li>
- </ul>
- </section>
+ </p>
+ </section>
+
+ <section name="Delivery analysis">
+ <p>Going beyond tools like <i>postal</i>, Postage tries to capture its
test mails on the target location, records statistics and validates the result.
+ So you can see not only the load, but also track successful and
failed deliveries.</p>
+ </section>
+
+ <section name="Track Server resource consumption">
+ <p>Postage is able to monitor the Server for memory and thread
consumption, if it is running under Java 5 SE.</p>
+ </section>
+
+ <section name="Pluggability">
+ <p>Per default, Postage generates test mails containing one textual and
one binary part each having random sizes.</p>
+ <p>This default behavior can be overridden on a email profile basis.
User defined MailFactory and MailValidator classes which generate and handle
use-case-specific mails can be plugged in very easily.</p>
+ </section>
+
</body>
</document>
Modified: james/postage/trunk/src/site/xdoc/prepare_james.xml
URL:
http://svn.apache.org/viewvc/james/postage/trunk/src/site/xdoc/prepare_james.xml?view=diff&rev=450345&r1=450344&r2=450345
==============================================================================
--- james/postage/trunk/src/site/xdoc/prepare_james.xml (original)
+++ james/postage/trunk/src/site/xdoc/prepare_james.xml Tue Sep 26 23:36:28 2006
@@ -20,7 +20,7 @@
<document>
<properties>
<title>Prepare James</title>
- <author email="[email protected]">James jSPF Project
Team</author>
+ <author email="[email protected]">James Postage Project
Team</author>
</properties>
<body>
<section name="Prepare James">
Added: james/postage/trunk/src/site/xdoc/test_mail_format.xml
URL:
http://svn.apache.org/viewvc/james/postage/trunk/src/site/xdoc/test_mail_format.xml?view=auto&rev=450345
==============================================================================
--- james/postage/trunk/src/site/xdoc/test_mail_format.xml (added)
+++ james/postage/trunk/src/site/xdoc/test_mail_format.xml Tue Sep 26 23:36:28
2006
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Postage test mail format conventions</title>
+ <author email="[email protected]">James Postage Project
Team</author>
+ </properties>
+ <body>
+ <section name="Postage standard mail headers">
+ <p>To recognize its own mails, Postage adds a couple of headers to its
test mails. AbstractMailFactory takes care for adding those headers
correctly.</p>
+ <p><code>X-James-Postage=This is a test mail sent by James
Postage</code></p>
+ <p><code>X-James-Postage-Count=1158086107828-1</code> where
"1158086107828" is constant for the whole scenario run while "1" is incremented
with every test mail.</p>
+ <p><code>X-James-Postage-Count=PROFORMA</code> is used for all mails in
the startup phase.</p>
+ <p><code>Message-ID=Postage-1158086175218</code> where "1158086175218"
is a time stamp distinguishing this mail from all others.</p>
+
<p><code>X-James-Validator=org.apache.james.postage.mail.AbstractMailFactory</code></p>
+ <p>These headers are used for identifying, matching and validating test
mails. If headers are missing, the result report can not be build properly.</p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
