pgoldstein 2002/12/02 03:31:56
Modified: src/xdocs custom_mailet_2_1.xml custom_matcher_2_1.xml
provided_mailets_2_1.xml spoolmanager_2_1.xml
using_database_2_1.xml
Added: src/xdocs documentation_2_1.xml usingTLS_2_1.xml
Removed: src/xdocs table_of_contents_2_1.xml
Log:
Adding the next revision of the docs for 2.1. Not quite done, but getting there.
Revision Changes Path
1.2 +2 -1 jakarta-james/src/xdocs/custom_mailet_2_1.xml
Index: custom_mailet_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/custom_mailet_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- custom_mailet_2_1.xml 1 Dec 2002 09:55:00 -0000 1.1
+++ custom_mailet_2_1.xml 2 Dec 2002 11:31:56 -0000 1.2
@@ -50,7 +50,8 @@
method is invoked each time a mail message is to be processed by the mailet. The
message is
passed in as an instance of the Mail interface, which is part of the Mailet API.</p>
<p>The Mail interface is essentially a light wrapper around JavaMail's MimeMessage
class with a
-few important differences..</p>
+few important differences. See the Javadoc for the interface for a description of
the additional
+methods available on this wrapper.</p>
</subsection>
<subsection name="Destruction">
<p>As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the
container
1.2 +64 -1 jakarta-james/src/xdocs/custom_matcher_2_1.xml
Index: custom_matcher_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/custom_matcher_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- custom_matcher_2_1.xml 1 Dec 2002 09:55:00 -0000 1.1
+++ custom_matcher_2_1.xml 2 Dec 2002 11:31:56 -0000 1.2
@@ -8,7 +8,70 @@
<body>
<section name="Writing a Custom Matcher">
-<p></p>
+<p>Implementing a custom matcher is generally a simple task, most of whose
complexity
+lies in coding the actual work to be done by the matcher. This is largely due to
the
+simplicity of the Matcher interface and the fact that a couple of abstract Matcher
template
+classes are provided in the Mailet package. These two classes, GenericMatcher and
+GenericRecipientMatcher, greatly simplfy the task of Matcher authoring.</p>
+<p>As discussed elsewhere in this manual, the Matcher interface does not simply
match
+or not match a particular message. Rather, it returns some subset of the original
message
+recipients as a result of the match(Mail) method. This leads to the two different
abstract
+Matcher implementations.</p>
+<p>The first, GenericMatcher, is intended for matchers where recipient evaluation
is not
+necessary. Basically, you should subclass this implementation if your matcher is
going to
+return all or none of the recipients.</p>
+<p>When subclassing this class, there are four methods that potentially need to be
+overridden. These are getMatcherInfo(), init(), match(Mail), and destroy(). More
on these
+anon.</p>
+<p>The second implementation, GenericRecipientMatcher, is intended for those
matchers where
+each recipient is evaluated individually. It is a subclass of GenericMatcher, and
inherits
+most of its behavior from that class. The only major difference is that subclasses
are
+expected to override matchRecipient(MailAddress) rather than match(Mail).</p>
+<subsection name="Configuration">
+<p>Matchers are passed a single String as part of their configuration.
Interpretation of this
+list is left entirely to the body of the Matcher. This String value is available
in
+the body of the Matcher through use of the getCondition() method of the
+GenericMatcher class. This method returns the String value passed to the Matcher,
and returns
+null if no value is set. The method getCondition() is available inside the init(),
destroy(), match(Mail),
+and matchRecipient(MailAddress) methods.</p>
+</subsection>
+<subsection name="Logging">
+<p>There is a simple logging mechanism provided by the Mailet API. It does not
support
+logging levels, so any log filtering will have to be implemented in the Matcher
code.
+Logging is done by calling one of the two logging methods on
GenericMatcher/GenericRecipientMatcher - log(String)
+or log(String,Throwable). Logging is available inside the init(), destroy(),
match(Mail),
+and matchRecipient(MailAddress) methods.</p>
+<p>The value of getMatcherInfo() for the Matcher is prepended to the log entries
for that
+Matcher. So it may be desirable for you to override this method so you can
distinguish Matcher
+log entries by Matcher.</p>
+</subsection>
+<subsection name="Initialization">
+<p>As part of the Matcher lifecycle, a Matcher is guaranteed to be initialized
immediately after
+being instantiated. This happens once and only once for each Matcher instance.
The
+Initialization phase is where configuration parsing and per-Matcher resource
creation generally
+take place. Depending on your Matcher, it may or may not be necessary to do any
initialization
+of the Matcher. Initialization logic is implemented by overriding the init()
method of
+GenericMatcher/GenericRecipientMatcher.</p>
+</subsection>
+<subsection name="Matching">
+<p>It is the matching phase where the Matcher's work is done. The exact form of
this phase largely
+depends on which Matcher superclass is subclassed.</p>
+<p>If GenericMatcher is being subclassed, it is the match(Mail) that is
implemented. As described
+above, this method returns a Collection of MailAddresses that is a subset of the
original
+recipients for the Mail object.</p>
+<p>If it is a purely recipient-filtering Matcher, then the GenericRecipientMatcher
should be
+subclassed. In this case, developers must provide an implementation of the
+matchRecipient(MailAddress) method. This method returns true if the recipient
matches,
+and false otherwise.</p>
+</subsection>
+<subsection name="Destruction">
+<p>As part of the Matcher lifecycle, a Matcher is guaranteed to be destroyed when
the container
+cleans up the Matcher. This happens once and only once for each Matcher instance.
The
+Destruction phase is where per-Matcher resource release generally takes place.
Depending
+on your Matcher, it may or may not be necessary to do any destruction
+of the Matcher. Destruction logic is implemented by overriding the destroy()
method of
+GenericMatcher/GenericRecipientMatcher.</p>
+</subsection>
</section>
</body>
</document>
1.2 +59 -0 jakarta-james/src/xdocs/provided_mailets_2_1.xml
Index: provided_mailets_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/provided_mailets_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- provided_mailets_2_1.xml 1 Dec 2002 09:55:00 -0000 1.1
+++ provided_mailets_2_1.xml 2 Dec 2002 11:31:56 -0000 1.2
@@ -35,6 +35,39 @@
</ul>
</p>
</subsection>
+<subsection name="AvalonListserv">
+<p>Provides basic list server functionality. Implements basic filters for emails
sent to the list,
+including restriction of senders to members, diallowing attachments in list
messages, and subject line
+processing</p>
+<p>Parameters:
+<ul>
+<li><strong>repositoryName</strong> (required) - the name of the user repository
that contains the users
+for this list.</li>
+<li><strong>membersonly</strong> (optional) - whether only members of the list can
send messages to this
+list. Defaults to false.</li>
+<li><strong>attachmentsallowed</strong> (optional) - whether attachments are
allowed in messages sent to this
+list. Defaults to true.</li>
+<li><strong>replytolist</strong> (optional) - whether the reply-to address for all
messages sent to this
+list is set to the list address. Defaults to true.</li>
+<li><strong>subjectprefix</strong> (optional) - a String value. If set, this value
is prepended to the subject
+line of all messages sent to the list.</li>
+<li><strong>autobracket</strong> (optional) - a boolean value. If a subjectprefix
is set, this value determines
+whether the prefix is bracketed before being prepended to the subject line.
Defaults to true.</li>
+</ul>
+</p>
+</subsection>
+<subsection name="AvalonListservManager">
+<p>Processes list management commands of the form <list-name>-on@<host>
and
+<list-name>-off@<host> where <list-name> and lt;host> are
arbitrary. Note
+that this should be used in tandem with a CommandForListserv matcher to ensure that
only commands
+intended for a specific list are processed.</p>
+<p>Parameters:
+<ul>
+<li><strong>repositoryName</strong> (required) - the name of the user repository
that contains the users
+for this list.</li>
+</ul>
+</p>
+</subsection>
<subsection name="Forward">
<p>Description: This mailet forwards the message to a set of recipients.</p>
<p>Parameters:
@@ -55,6 +88,18 @@
</ul>
</p>
</subsection>
+<subsection name="JDBCVirtualUserTable">
+<p>Description: This mailet does complex alias translation for email addresses
stored in a database table.</p>
+<p>Parameters:
+<ul>
+<li><strong>table</strong> (required) - the URL describing the database table.
This URL has the form
+db://<data-source>/<table> where <data-source> and <table>
are the names of
+the data-source as defined in config.xml and the table in the database.</li>
+<li><strong>sqlquery</strong> (optional) - the text of the SQL query used by the
mailet to do user
+lookup. The default is "select VirtualUserTable.target_address from
VirtualUserTable, VirtualUserTable as VUTDomains where (VirtualUserTable.user like ?
or VirtualUserTable.user like '\\%') and (VirtualUserTable.domain like ? or
(VirtualUserTable.domain like '\\%' and VUTDomains.domain like ?)) order by
concat(VirtualUserTable.user,'@',VirtualUserTable.domain) desc limit 1"</li>
+</ul>
+</p>
+</subsection>
<subsection name="LocalDelivery">
<p>Description: This mailet delivers messages to local mailboxes.</p>
<p>Parameters: None.</p>
@@ -93,6 +138,20 @@
the original recipient address. This mailet is inserted automatically by James at
the head of the root
processor.</p>
<p>Parameters: None.</p>
+</subsection>
+<subsection name="Redirect">
+<p>Description: This mailet provides configurable redirection services. Users are
encouraged to consult
+the source and subclass this Mailet to produce a variety of effects.</p>
+<p>Parameters:
+<ul>
+<li><strong>prefix</strong> (optional) - an prefix for the subject line of the
redirected message. If set, this is
+prepended to the original subject line. If unset, the subject line is left
unchanged.</li>
+<li><strong>passThrough</strong> (optional) - a boolean value (true/false)
indicating whether
+processing should continue on the message is on. If false, the original message is
GHOSTed. Defaults to false.</li>
+<li><strong>debug</strong> (optional) - a boolean value (true/false) indicating
whether debugging is
+on. Defaults to false.</li>
+</ul>
+</p>
</subsection>
<subsection name="RemoteDelivery">
<p>Manages delivery of messages to recipients on remote SMTP hosts.</p>
1.2 +1 -1 jakarta-james/src/xdocs/spoolmanager_2_1.xml
Index: spoolmanager_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/spoolmanager_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- spoolmanager_2_1.xml 1 Dec 2002 09:55:00 -0000 1.1
+++ spoolmanager_2_1.xml 2 Dec 2002 11:31:56 -0000 1.2
@@ -55,7 +55,7 @@
the processor tree until they reach the end of a processor or are marked completed
by a mailet.</p>
-<p>More on configuration of the SpoolManager can be found here.</p>
+<p>More on configuration of the SpoolManager can be found <a
href="spoolmanager_configuration.html">here</a>.</p>
<p>Much of the power of James lies in the SpoolManager component. Custom matchers
and
mailets can be easily developed to address an administrator's particular needs.
The
1.2 +46 -1 jakarta-james/src/xdocs/using_database_2_1.xml
Index: using_database_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/using_database_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- using_database_2_1.xml 1 Dec 2002 09:55:00 -0000 1.1
+++ using_database_2_1.xml 2 Dec 2002 11:31:56 -0000 1.2
@@ -7,7 +7,52 @@
</properties>
<body>
-<section name="Database Configuration">
+<section name="Database Configuration">
+<p>James has the capacity to use a JDBC-compatible database for storage of both
message and user
+data. This section explains how to configure James to utilize a database for
storage.</p>
+<subsection name="Requirements">
+<p>Using James with a database backend has certain requirements. Database
configuration is
+extremely vendor-specific, so we can only state the requirements in general
terms.</p>
+<p>There must be a database instance accessible from the James server. An account
with appropriate
+privileges (select, insert, delete into tables, and on initial startup creation of
tables) and
+with sufficient quota for the data to be inserted into the database must be
available. Also,
+since James will use JDBC to access the database, an appropriate JDBC driver must
be
+available for installation.</p>
+<p>It is important to verify the functionality of the database before attempting to
configure
+James to use it as a repository. This will help ensure that configuration issues
are properly
+identified.</p>
+</subsection>
+<subsection name="Connection Configuration">
+<p>Configuring the Phoenix container to work with JDBC is the first step in
enabling James database support.</p>
+<p>First, Phoenix must be able to load the JDBC classes. To make these classes
available to Phoenix, place the
+jar/zip files for the JDBC driver in the lib subdirectory of the James installation
directory. Any additional
+libraries upon which the JDBC library depends that are not part of the standard
Java distribution should also be
+added to this directory.</p>
+<p>Please note that a MySQL driver is included as part of the James distribution and
+so there is no need to add such a driver to the lib directory.</p>
+<p>Second, the config.xml must be modified so that Phoenix initializes the database
connections. The relevant
+configuration is in the database-connections block. The database-connections tag
has only a single child tag,
+data-sources. This latter tag is a simple container tag for a number of child
elements. It is these child
+elements, <strong>data-source</strong> elements, that define the database
connections.</p>
+<p>Each <strong>data-source</strong> tag has a required attribute,
<strong>name</strong>. This value
+must be unique to each <strong>data-source</strong> element. It is this
<strong>name</strong> that will
+be used to specify the database connection in other parts of the config.xml
file.</p>
+<p>The <strong>data-source</strong> element has five children, all of whom are
required.
+<ul>
+<li><strong>driver</strong> - The class name of the database driver to be used.</li>
+<li><strong>dburl</strong> - The JDBC connection URL for your database/driver.</li>
+<li><strong>user</strong> - The user id of the database account to be used by this
connection.</li>
+<li><strong>password</strong> - The password of the database account to be used by
this connection.</li>
+<li><strong>max</strong> - The maximum number of JDBC connections to be used
concurrently by this data-source.</li>
+</ul>
+</p>
+</subsection>
+<subsection name="Known Issues">
+<p>There are some vendor-specific subtleties in using databases with James that
have been observed
+by some users. These issues (and methods to resolve them) are recorded on the
+<a href="FAQ.html">James FAQ</a> as they are reported. Please consult the FAQ if
you encounter any
+difficulties.</p>
+</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/documentation_2_1.xml
Index: documentation_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Table of Contents</title>
</properties>
<body>
<section name="James 2.1">
<p>
The Java Apache Mail Enterprise Server (a.k.a. Apache James) is a 100% pure Java
SMTP and POP3 Mail
server and NNTP News server designed to be a complete and portable enterprise mail
engine
solution. James is based on currently available open protocols.
</p>
<p>
The James server also serves as a mail application platform. The James project
hosts the Apache Mailet API,
and the James server is a Mailet container. This feature makes it easy to design,
write, and deploy
custom applications for mail processing. This modularity and ease of customization
is one of James'
strengths, and can allow administrators to produce powerful applications
surprisingly easily.
</p>
<p>
James is built on top of version 4.1.3 of the <a
href="http://jakarta.apache.org/avalon";>Avalon Application Framework</a>. This
framework encourages a set of good development practices such as Component Oriented
Programming and
Inversion of Control. The standard distribution of James includes version 4.0.1 of
the
<a href="http://jakarta.apache.org/avalon/phoenix";>Phoenix Avalon Framework
container</a>. This stable
and robust container provides a strong foundation for the James server.
</p>
<p>
This documentation is intended to be an introduction to the concepts behind the
James implementation, as well
as a guide to installing, configuring, (and for developers) building the James
server.
</p>
<subsection name="Table of Contents">
<p>
I. James Concepts
<ul>
<li><a href="summary_2_1.html">Summary</a></li>
<li><a href="spoolmanager_2_1.html">SpoolManager</a></li>
<li><a href="repositories_2_1.html">Repositories</a></li>
<li><a href="mailet_api_2_1.html">The Mailet API</a></li>
</ul>
II. How To Build James
<ul>
<li><a href="build_instructions_2_1.html">Building James</a></li>
</ul>
III. How To Install James
<ul>
<li><a href="installation_instructions_2_1.html">Installing James</a></li>
</ul>
IV. Configuring James
<ul>
<li><a href="pop3_configuration_2_1.html">POP3 Server Configuration</a></li>
<li><a href="smtp_configuration_2_1.html">SMTP Server Configuration</a></li>
<li><a href="nntp_configuration_2_1.html">NNTP Server Configuration</a></li>
<li><a href="fetchpop_configuration_2_1.html">FetchPOP Configuration</a></li>
<li><a href="remotemanager_configuration_2_1.html">RemoteManager
Configuration</a></li>
<li>Repository Configuration</li>
<li><a href="spoolmanager_configuration_2_1.html">SpoolManager
Configuration</a></li>
<li><a href="serverwide_configuration_2_1.html">Server-wide Configuration</a></li>
<li><a href="adding_users_2_1.html">Adding Users</a></li>
<li><a href="provided_matchers_2_1.html">Provided Matchers</a></li>
<li><a href="provided_mailets_2_1.html">Provided Mailets</a></li>
</ul>
V. Common Configurations
<ul>
<li><a href="smtp_auth_2_1.html">Using SMTP AUTH</a></li>
<li><a href="james_and_sendmail.html">Using a Database with James</a></li>
<li><a href="usingTLS_2_1.html">Using TLS/SSL</a></li>
<li><a href="james_and_sendmail.html">James and Sendmail</a></li>
</ul>
VI. Customizing James
<ul>
<li><a href="custom_matcher_2_1.html">How to write a custom Matcher</a></li>
<li><a href="custom_mailet_2_1.html">How to write a custom Mailet</a></li>
</ul>
V. Other Information
<li><a href="FAQ.html">The James FAQ</a></li>
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/usingTLS_2_1.xml
Index: usingTLS_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Using TLS</title>
</properties>
<body>
<section name="James 2.1 - Using TLS">
<p>
This document explains how to enable James 2.1 services to use Transport Layer
Security (TLS) for encrypted client-server communication.</p>
</section>
<subsection name="Making TLS/SSL Server Sockets Available Inside James">
<p>James uses the Sun Java Secure Sockets Extension (JSSE) infrastructure to provide
TLS/SSL
sockets. JSSE comes packaged with several vendor Java distributions (i.e. Sun Java
1.4.x,
IBM Java 1.3.x). For these distributions, please follow the vendor provided
instructions for
configuring the JVM to use JSSE services.</p>
<p>If you are using a Java distribution that does not include JSSE as part of the
distribution you will need to download the JSSE package separately. It can be
obtained from
<a href="http://java.sun.com/jsse";>here</a>. Please follow Sun's instructions for
installation
and configuration of JSSE.</p>
<p>In either case, you will need to statically define a JSSE TLS provider. In
general, this
is the default installation.</p>
<p>Once you've installed JSSE, James still needs to be configured to take advantage
of the JSSE
functionality.</p>
</subsection>
<section name="Enable TLS">
<p>
Using JAMES with TLS. You need to do three things over and above the
normal operation of James:
<ul>
<li>In config.xml, uncomment the TLS listener defintion.</li>
<li>In config.xml, uncomment the <useTLS>TRUE</useTLS> element
for the service you want to use TLS. It is currently available for
remote manager and POP3. (If using POP3 over TLS, it is probably best
to change port to 995, which is the IANA designated POP3S port).</li>
<li> Ensure that avalonTestKeys is in the conf directory. You may need
to manually extract this from the Avalon.jar (with: jar xvf Avalon.jar
conf/avalonTestKeys). Note that this is a self-signed certificate for
test purposes only. You can specify a different server certificate in
the config.xml file.</li>
</ul>
</p>
<p>
Start James
</p>
</section>
<section name="Verifying a TLS-enabled James Service">
<p>After you've configured a particular service to use TLS/SSL connections, it
should no longer
accept normal TCP/IP connections. You can execute this negative test case by using
a telnet
client to directly connect to the service port. The telnet connection should simply
hang until
the client times out.</p>
<p>
(Positive Test) Use an SSL client to open a socket to the appropriate port.
I used openssl from www.openssl.org to test this.
E.g. openssl s_client -connect localhost:4555. You should see the normal
remote manager or POP3 server greeting and have normal operation.
<br>
- If, using openssl s_client, you get a connection refused/ error no
111, just try again. This probably means you got to the port before it
was ready.
</br>
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
