Package org.faceless.publisher.ext

Class MailServerExtension

java.lang.Object
org.faceless.publisher.ext.MailServerExtension
All Implemented Interfaces:
ReportFactoryExtension
public class MailServerExtension extends Object implements ReportFactoryExtension

The MailServerExtension offers a standard way to access email messages, using the "imap" URL schema described in RFC5092.

Authentication is now rarely done with usernames and password alone, so this class makes use of the KeyStore class, to store authorization data as a SecretKey. This will work with any JCE, JCEKS or PKCS12 format keystore, and although not a necessary part of the API it is a convenient and secure way to store the arbitrary authorization data required for IMAP authentication.

The example below is a complete example showing how this works. A KeyStore is specified, and will be created if it doesn't exist. 


 // Either javax.mail or jakarta.mail is required, the code below
 // works with either
 import javax.mail.*;
 import javax.mail.internet.*;

 // First create the extension and add it to the ReportFactory
 ReportFactory factory = new ReportFactory();
 MailServerExtension ext = new MailServerExtension(factory);
 factory.getReportFactoryExtensions().add(ext);

 String username = "user@example.com";
 char[] password = "secret".toCharArray();
 
 // Configure the extension to use a particular keystore,
 // then load the authorization data from it. If it's not
 // there or the keystore is missing, create the authorization
 // data then save it to the keystore for next time.
 ext.setKeyStore(Paths.get("keystore.jceks"), password, "jceks", null);
 Json json = ext.load(username, password);
 if (json == null) {
     // First time login.
     MailServerExtension.GMailHelper gmail = new MailServerExtension.GMailHelper();
     gmail.setEmail(username);
     gmail.setClientId("NNNNN.apps.googleusercontent.com");
     gmail.setClientSecret("NNNNN");
     gmail.setRedirectURI("http://127.0.0.1:8000/oauth");
     json = ext.save(username, password, gmail.create());
 }
 URL2 uri = ext.createStore(json);
 Store store = (Store)ext.getStore(uri);

 // We are now connected to the IMAP server. To convert a message to PDF:
 // Option 1 - load message via the object directly
 Folder folder = store.getFolder(foldername);
 if (!folder.isOpen()) {
    folder.open(Folder.READ_ONLY);
 }
 Message message = folder.getMessage(num);

 Report report = factory.createReport();
 report.load(message);

 // Option 2 - load message via an "imap" URL
 URL2 msguri = uri.resolve("/"+folderName+"/;uid="+((UIDFolder)folder).getUID(message));
 report.load(msguri);

The JSON configuration

The configuration for connecting to mail server is represented as a JSON object. The intention is this class will ship with various helpers to configure output for common mail service providers, and if one is available for your service that's what we recommend. Otherwise, a JSON object can be created manually. The fields are:

  • scheme - the Mail URL scheme, should always be "imap"
  • store -the store type, should always be "imaps"
  • email -the email address being accessed
  • server -the email server address, eg "imap.gmail.com"
  • properties -an optional map of strings used configure the Java IMAP connection. A typical example would be {"mail.imap.auth.mechanisms":"XOAUTH2","mail.imaps.sasl.enable":"true"}}
  • auth - a map containing the authorization details - it should contain a type string and data, a map of values specific to the authorizer. For OAUTH2 authorization, auth.type should be "oauth2", and auth.data a map as described in the OAuth2 class.

Here is a full example of a configuration for the Google "Gmail" service, as generated by the MailServerExtension.GMailHelper class. 


 {
   "scheme": "imap",
   "server": "imap.gmail.com",
   "store": "imaps",
   "email": "test@example.org",
   "properties": {
     "mail.imap.auth.mechanisms": "XOAUTH2",
     "mail.imaps.sasl.enable": "true"
   },
   "auth": {
     "type": "oauth2",
     "data": {
       "auth_uri": "https://accounts.google.com/o/oauth2/v2/auth",
       "token_uri": "https://www.googleapis.com/oauth2/v4/token",
       "redirect_uri": "http://127.0.0.1:8080/oauth",
       "client_id": "nnnnnnnn.apps.googleusercontent.com",
       "client_secret": "nnnnnnnn",
       "scope": "https://mail.google.com/",
       "protocol": {
         "auth": {
           "prompt": "consent"
         }
       },
     }
   },
 }

This class requires an implementation of either the jakarta.mail.internet or javax.mail.internet package in the classpath; if neither is found, an exception will be thrown from the constructor.