===================
Building the add-on
===================
Ant scripts are provided to be used to build the mail add-on.
In order to be able to use the mail add-on, nuxeo-platform-mail-core
and nuxeo-platform-mail-web ought to be deployed.

For this, following steps can be followed:
1. In the add-on parent folder (nuxeo-platform-mail), create a 
build.properties file, based on the provided build.properties.sample one.
2. In nuxeo-platform-mail-core and nuxeo-platform-mail-web folders, just
issue "ant deploy" (or "ant") command. The concerning module will be 
compiled and copied to nuxeo.ear/plugin folder.
3. If changes of the xhtml files need to be tested in "hot deployment"
mode, just issue "ant web" command from nuxeo-platform-mail-web folder.
4. One more thing to be done is to configure the scheduler service sending 
the events which are triggering the email account checks. For this, 
"ant scheduler" command can be issued from nuxeo-platform-mail-core folder.
This way, a scheduler configuration file (nxmail-scheduler-config.xml) is
copied to nuxeo.ear/config folder. If other interval than the default one
(every 30 minutes) is wanted, the this file can be changed accordingly 
(<chronExpression> tag).

==============================================================================

=======================
Some functional details
=======================
One important aspect of nuxeo-platform-mail consists in the fact that multiple
email connections can be dinamically configured from the web UI interface.

This is done by creating "Email folder" documents, which contain the parameters
needed in order to connect to the email account. On a number of minutes (this
number is configured in nxmail-scheduler-config.xml - please see above), all
the email accounts defined by the "Email folders" are checked for new incoming
mail. For every new mail found in a certain account, a new corresponding 
"Email message" is created as a child of the "Email folder" corresponding to
the email account.

Also, an email account check can be triggered for a certain "Email folder", 
by clicking the "Check email" button which can be found in the view page of
an "Email folder" document.

Note: For performance reasons, only a limited number of emails are
imported for every account check. This limit can be set when a the
creation/modification of a MailFolder document.

==============================================================================

=================
SSL Configuration
=================
If you connect to your mail server using SSL, your server needs to
have a valid certificate, that is, a certificate that is issued by a
known Authority. If this is not the case (you're using a self-made
certificate), then the JVM will refuse to connect and you'll have a
SSLHandShake error.

To be able to connect with a server with a self-made certificate, you
need to add this certificate to the trusted certificate using keytool
with a command such as (see man keytool for more information):
keytool -import -trustcacerts -file mail.cer -keystore thekeystore

If you don't have the certificate of the mail server you can get it
with the following command:
openssl s_client -connect my.mailserver.com:PORT

You can either import the certificate in the cacerts of your JVM, or
create a new keystore and start the jvm with:
-Djavax.net.ssl.trustStore=/home/foo/.keystore

Another option is to use an helper class from:
http://blogs.sun.com/andreas/entry/no_more_unable_to_find
and to follow this step:

1/ run the TestConnection class in eclipse as an application with your
   connection parameters

2/ if not working (error 'unable to find valid certification path to
   requested target') compile the java class:
   $ java InstallCert.java

3/ execute on imap server for instance:
   $ java InstallCert mail.example.com
   or
   $ java InstallCert mail.example.com:993

4/ make sure it is a good key before entering, and make sure it's been
   added to the default keystore in $JAVA_HOME/jre/lib/security/cacerts

5/ reproduce steps if needed, *do not forget to delete* the local file
   'jssecacerts' that's been created (otherwise the default keystore won't
   be updated anymore)

To test your setting you can use this class:
A TestConnection class sample

public class TestImapConnection {

    public static void main(String args[]) throws Exception {
        Properties props = new Properties();

        props.put("user", "email@example.com");
        props.put("password", "password");

        props.put("mail.store.protocol", "imap");
        props.put("mail.imap.host", "mail.example.com");
        props.put("mail.imap.port", "993");
        props.put("mail.imap.ssl.protocols", "SSL");
        props.put("mail.imap.starttls.enable", "true");

        props.put("mail.imap.socketFactory.class",
                "javax.net.ssl.SSLSocketFactory");
        props.put("mail.imap.socketFactory.port", "993");
        props.put("mail.imap.socketFactory.fallback", "false");

        Session session = Session.getDefaultInstance(props);

        Store store = session.getStore();
        System.err.println("connecting");
        store.connect(props.getProperty("user").toString(), props.getProperty(
                "password").toString());

        store.close();
        System.err.println("done");
    }

}

