james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ber...@apache.org
Subject svn commit: r450345 - in /james/postage/trunk/src/site: site.xml xdoc/custom_test_mails.xml xdoc/index.xml xdoc/prepare_james.xml xdoc/test_mail_format.xml
Date Wed, 27 Sep 2006 06:36:29 GMT
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="server-dev@james.apache.org">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>&lt;send&gt;</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>
+ &lt;profile name="int-ext" source="intern" target="extern"&gt;
+     &lt;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>
+     /&gt;
+ &lt;/profile&gt;
+          </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="server-dev@james.apache.org">James jSPF Project Team</author>
+    <author email="server-dev@james.apache.org">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="server-dev@james.apache.org">James jSPF Project Team</author>
+    <author email="server-dev@james.apache.org">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="server-dev@james.apache.org">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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message