james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pgoldst...@apache.org
Subject cvs commit: jakarta-james/src/xdocs documentation_2_1.xml usingTLS_2_1.xml custom_mailet_2_1.xml custom_matcher_2_1.xml provided_mailets_2_1.xml spoolmanager_2_1.xml using_database_2_1.xml table_of_contents_2_1.xml
Date Mon, 02 Dec 2002 11:31:56 GMT
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 &lt;list-name&gt;-on@&lt;host&gt;
and 
  +&lt;list-name&gt;-off@&lt;host&gt; where &lt;list-name&gt; and
lt;host&gt; 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://&lt;data-source&gt;/&lt;table&gt; where &lt;data-source&gt;
and &lt;table&gt; 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 &lt;useTLS&gt;TRUE&lt;/useTLS&gt;
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:james-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:james-dev-help@jakarta.apache.org>


Mime
View raw message