tabellarium is a library that provides the means to execute tasks against e-mail messages in one folder in the e-mail mailbox. Those tasks can be anything from reading and processing e-mails, saving them to a offline resource to modifying some state on the server. The library only works with IMAP mailboxes and only in one folder at the time. But multiple instances can work with multiple folders as long as they are not the same.
Main behavior is defined in the MailboxTaskExecutor
interface.
It’s only implementation is ImapMailboxFolderTaskExecutor
that works with IMAP
mailboxes. You can instantiate it like this:
MailboxTaskExecutor executor =
new ImapMailboxFolderTaskExecutor
("hostAddress", "username", "password", "Inbox");
The constructor arguments are self-explanatory. ImapMailboxFolderTaskExecutor
has some other settings like port number, ‘should use IMAPS’ and such. Besides
them there are 3 things that should require some attention. In code:
// after doing something with an e-mail message
// mark it for deletion
executor.setDeleteAfterRetrieval(false);
// consider seen e-mails when executing tasks
executor.setRetrieveSeenEmails(true);
// Batch size means that 100 e-mail messages will be retrieved
// when executing tasks. If there are less than 100 then all
// will be retrieved. If batch size is 0 than all e-mails
// will be considered.
executor.setBatchSize(100);
How tabellarium actually works? Again in code:
executor.executeForEachEmail(message -> {
// do something with the e-mail message...
});
This will connect to the mailbox with information from the constructor arguments and execute the task defined against each e-mail message. The settings defined before also come into play here.
If any exception occurs during the task execution the executor will try to revert the status flags if they are changed - specifically revert SEEN and DELETED.
There are some built in tasks - email handlers because they implement the
EmailHandler
interface - in the library that provide some basic
functionalities. One of them is:
executor.executeForEachEmail(
new ChangeMessageFlagEmailHandler("deleted", true));
This will set the ‘deleted’ flag to true for each mail, essentially deleting them
on the server. In order for this to work (this and any task that modifies
state on the server) an active session must be maintained while executing the
task. This is the default behavior when providing the EmailHandler
instance
to the executor. But if you want to do something with the text of the e-mail,
for example writing it to a file, you will need to force the retrieval of the
body from the server. To do this provide an instance of the
UnlinkedEmailHandler
class to the executor.
Implementations provided in the library are PrintingEmailHandler
and
PrintInFileEmailHandler
that write the whole e-mail in provided stream and
in file, respectfully.
executor.executeForEachEmail(new PrintingEmailHandler(System.out));
executor.executeForEachEmail(
new PrintInFileEmailHandler("file name"));
Two other methods are defined in the API:
// This will retrieve the copy of the messages from the mailbox.
// It will honor the settings defined above.
List<Message> messages = executor.retrieveEmails();
// This will return true if there are e-mails in the mailbox.
// Unlike the other methods it honors only
// setRetrieveSeenEmails flag.
boolean result = executor.areThereRemainingEmails();
These can possibly be just another tasks that are passed to the
executeForEachEmail
method and probably will be refactored in that manner
in the future, but for now they are separate methods.
Check out the repo for source.