Migrating to Simple Java Mail 5.0.0

Builders all the way down
Why builders?
So what API changed?
Conditional config?
Changes to Spring support
TransportStrategy renamed
Libraries DKIM and email-rfc2822-validator not included in the JAR anymore

Builders all the way down

With all the possible ways to configure Email and Mailer instances, the library had only one option left to streamline API, avoid the Telescoping Constructor anti-pattern and keep things manageable: fluent builders.

Why builders?

With fluent builders, we can tightly control valid combinations, logical decision paths and easily provide alternative methods.
At the same time we can move all the mutation logic to the builders and produce mostly immutable objects.
Finally, we're now able to centralize our documentation around the builders and refer to it from wherever it is used.

So what API changed?

All the constructors and mutation methods of Mailer have been replaced by the MailerBuilder.
Similarly, all the constructors and mutation methods of Email have been replaced by the EmailBuilder.

// So instead of:
Email email = new Email();
email.setFromAddress(...)

// you start with EmailBuilder instead:
Email email = EmailBuilder.startingFromBlank()
        .from(...)
        .buildEmail();

// And instead of:
Mailer mailer = new Mailer(/*...many options...*/);
mailer.setDebug(true);

// you start with MailerBuilder instead:
Mailer mailer = MailerBuilder.
        //.manyOptions()
        .withDebugLogging(true)
        .buildMailer();

Furthermore all the reading methods on Mailer have been consolidated into parameter objects and made available where previously not yet disclosed.

// For example, to read out the thread pool size:
Mailer mailer = ...;
int poolsize = mailer.getOperationalConfig().getThreadPoolSize();

The following information is available to you now:

email.getAnythingYouCanSetWithABuilder();

mailer.getSession(); // the only mutable object
mailer.getTransportStrategy();
mailer.getServerConfig();
mailer.getProxyConfig();
mailer.getOperationalConfig();
mailer.getEmailAddressCriteria();

Conditional configuration

Here's a simple example of conditional configuration using builders

MailerRegularBuilder builder = MailerBuilder.withSMTPServer("smtp.host.com", 25);

if (yourCondition) 
    builder.withSMTPServerPort(26);
    builder.withTransportModeLoggingOnly(false);


Mailer mailer = builder.buildMailer();

Changes to Spring support

The Java configuration has not changed, but Spring beans in XML configuration is not supported anymore out-of-the-box.

This is because there are no constructors or bean setters/getters anymore, which you would normally use to create a Spring bean in XML. The only way around this for XML configuration, is to provide your own builder method and refer to that from your bean xml so you can utilize the new builder API.

Refer to the configuration section to see some current Spring examples

TransportStrategy renamed

Due to security updates #105 and #111 a rename of the TransportStrategy enum was in order.

For v4, here are the possible values:

simplejavamail.transportstrategy=SMTP_PLAIN
simplejavamail.transportstrategy=SMTP_SSL
simplejavamail.transportstrategy=SMTP_TLS

For v5, the following will work:

simplejavamail.transportstrategy=SMTP
simplejavamail.transportstrategy=SMTPS
simplejavamail.transportstrategy=SMTP_TLS

Libraries DKIM and email-validator not included in the JAR anymore

Due to issues with updating (#120) and downloading sources (#122) for the externals libraries DKIM and email-rfc2822-validator, these dependencies are not included in the generated Simple Java Mail JAR anymore.

Instead, they are now included and updated like regular Maven dependencies again.

Note that the DKIM library is optional and only loaded when using the DKIM API, but email-rfc2822-validator is (still) included by default.

To include the DKIM library:

<dependency>
    <groupId>net.markenwerk</groupId>
    <artifactId>utils-mail-dkim</artifactId>
    <version>X.X.X</version>
</dependency>

email-rfc2822-validator is included by default, but you can update the version as follows:

<dependency>
    <groupId>com.github.bbottema</groupId>
    <artifactId>emailaddress-rfc2822</artifactId>
    <version>X.X.X</version>
</dependency>