Migrating to Simple Java Mail 5.0.0
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.
- 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
Similarly, all the constructors and mutation methods of
// 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.
The following information is available to you now:
// For example, to read out the thread pool size: Mailer mailer = ...; int poolsize = mailer.getOperationalConfig().getThreadPoolSize();
email.getAnythingYouCanSetWithABuilder(); mailer.getSession(); // the only mutable object mailer.getTransportStrategy(); mailer.getServerConfig(); mailer.getProxyConfig(); mailer.getOperationalConfig(); mailer.getEmailAddressCriteria();
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
For v5, the following will work:
simplejavamail.transportstrategy=SMTP_PLAIN simplejavamail.transportstrategy=SMTP_SSL simplejavamail.transportstrategy=SMTP_TLS
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.
email-rfc2822-validator is included by default, but you can update the version as follows:
<dependency> <groupId>net.markenwerk</groupId> <artifactId>utils-mail-dkim</artifactId> <version>X.X.X</version> </dependency>
<dependency> <groupId>com.github.bbottema</groupId> <artifactId>emailaddress-rfc2822</artifactId> <version>X.X.X</version> </dependency>