Feature: Make defaults and overrides a first class feature

[bbottema]

Until now, defaults were handled during Email construction, assuming defaults values where found in (system) properties (files). This approach worked fine for a long time, but had two disadvantages:

1. You can only control defaults on a global level, while defaults could be different between multiple Mailer instances, for example because their respective SMTP server had different policies for headers, from address, DKIM domain keys etc.
2. Programmatic defaults were only possible by managing the ConfigLoader properties directly. A separate step before using Email/Mailer builder API. It works and is relatively easy to do, but doesn't conform to Simple Java Mail's mission statement for a super simple and clean API.
3. You couldn't make exceptions on a field by field basis. Either you applied all defaults or you ignored them all using emailBuiler.ignoringDefaults().
4. Some operations were expensive and prohibitive for large scale operations. For example reading and processing a PKCS12 truststore for signing emails with S/MIME.

And of course, there was no capability for defining overrides. Defaults are for missing values, while overrides take precedence in any case.

A recent change alleviated some of these issues, but this this had a focus on performance, which meant only some properties were moved to the Mailer level (specifically S/MIME). That too with dedicated methods on the MailerBuilder, which wouldn't scale well if we were going to have all properties configurable that way. An even more recent change added defaults email instances and even overrides on the Mailer level, but this was a flawed implementation, as the properties from system/files/ConfigLoader were still applied during Email construction and then whatever was programmatically added as default on the Mailer was set during sending.

This issue aims to move all defaults/overrides to the Mailer level, via the existing EmailGovernance object. We're not having a single setXyzByDefault() for every property on the Mailer, but we simply set Email instances as defaults/overrides references on the governance object. If no defaults email is provided, a blank one will be created and populated from the system/files/ConfigLoader sources. This means that all expensive operations are executed only once and all properties are now evaluated only when sending emails. This also means that emails you create initially have no defaults applied and might look empty. You will have more control to have an Email created regularly, or create it with defaults/overrides applied right away (in case if you don't want to send an email, but still want a fully populated email, for example to use as a defaults email reference, or if you just want to use a helper method). And also you will be able to exclude specific properties from being defaulted or overridden. You can model advanced scenarios this way, allowing exceptions on exceptions on exceptions (define property file defaults, overwrite with programmatic defaults, have a specific email ignore a specific default altogether, but then an override can be enabled but also ignored the same way).

[bbottema]

Release in 8.0.0. I'm still updating the documentation on simplejavamail.org.

[bbottema]

• Defaults and overrides are now only applied when sending mail, logging mail or delegating mail to a CustomMailer.
• This means emailBuilder().build() might not be as populated as you expect. If you need a fully populated email for your own purposes, such as logging, handling or using one of Simple Java Mail's helper methods -but not sending-, you can use emailBuilder.buildEmailCompletedWithDefaultsAndOverrides()
• You can set Email instances as defaults or overrides reference using mailerBuilder.withEmailDefaults(Email) or mailerBuilder.withEmailOverrides(Email). All fields can be used.
• On Email level, you can set certain fields to be exempt completely from default values or overriding values, using emailBuilder.dontApplyDefaultValueFor(EmailProperty...) or emailBuilder.dontApplyOverrideValueFor(EmailProperty...).
• To complete innoculate your Email instance from having defaults or overrides set, use emailBuilder.ignoringDefaults(true) or ignoringOverrides(true), or when you start an email with EmailBuilder.ignoringDefaults() and EmailBuilder.ignoringOverrides().

You can create a new EmailGovernance using new EmailGovernanceImpl(...), but that's unintended. There is a builder missing to this neatly. This will come in 8.0.1.