Immutable mailer instance

[ggrossetie]

This is a proposition to replace the configure method.
Currently the mailer instance is mutable, when it gets reconfigured, it gets reconfigured globally.
The goal is to have an immutable mailer instance. See: #51 (comment)

Principle

• New module to provide a SMTPConfiguration from the Configuration object
  • This module can be overridden with play.modules.disabled (not sure if this the right way to do it) to provide a custom SMTPConfiguration (see samples)
• CommonsMailer injects a SMTPConfiguration

Note: I think it would be better to rename CommonsMailer to SMTPMailer and SMTPMailer to CommonsMailer.

Pros

• Immutable mailer instance
• If the mailer configuration is wrong, we get an error at the start of the server (i.e. when Guice initializes objects) rather than when the code is executed
• It's easy to (manually) instantiate a mailer with a custom configuration val mailer = new CommonsMailer(SMTPConfiguration("typesafe.org", 1234))

Cons

• It's less straight forward to configure the injected instance

  • write custom module and provider + disable the default module and enable the custom module

• "Cryptic" error message when the mailer configuration is wrong (because Guice is unable to create a SMTPConfiguration)

  ProvisionException: Unable to provision, see the following errors:
  
  1) Error in custom provider, java.lang.RuntimeException: host needs to be set in order to use this plugin (or set play.mailer.mock to true in application.conf)
  while locating play.api.libs.mailer.SMTPConfigurationProvider
  while locating play.api.libs.mailer.SMTPConfiguration
    for parameter 0 at play.api.libs.mailer.CommonsMailer.<init>(MailerPlugin.scala:86)
  while locating play.api.libs.mailer.CommonsMailer
  while locating play.api.libs.mailer.MailerClient
    for parameter 0 at controllers.ApplicationJava.<init>(ApplicationJava.java:18)
  while locating controllers.ApplicationJava
    for parameter 1 at router.Routes.<init>(Routes.scala:32)
  while locating router.Routes
  while locating play.api.inject.RoutesProvider
  while locating play.api.routing.Router
  Caused by: java.lang.RuntimeException: host needs to be set in order to use this plugin (or set play.mailer.mock to true in application.conf)
  

• Not binary compatible

[schmitch]

I'm also not a guice Guy, however on my side this looks really good, since that enables configuration via the database (which is what I want) and it is also immutable.

Also it's really hard to use it to create multiple Immutable mailers (you need to do a https://github.com/google/guice/wiki/AssistedInject for that (which is hard especially without any example code, for the most people)). But I don't think that too many people will need it without having that knowledge, so we could just ignore this for a while.

For the binary incompatible change, I didn't understand the rise to 3.0 (way too early, so I think not many people are on 3.0 yet so we could also just force them to ignore 3.0 or raise to 4.0)

[ggrossetie]

Also it's really hard to use it to create multiple Immutable mailers

It's pretty simple to do it without Guice:

val email = Email("Simple email", "Mister FROM <[email protected]>")
new SMTPMailer(SMTPConfiguration("typesafe.org", 1234)).send(email)
new SMTPMailer(SMTPConfiguration("playframework.com", 5678)).send(email)

[ggrossetie]

I've added a detailed explanation on how to configure the mailer instance: https://github.com/Mogztter/play-mailer/blob/immutable/user-manual.adoc

@jroper If this looks good to you, I would like to proceed with this pull request and release a 4.0.0-M1 version to get user feedback on this new API.

[ggrossetie]

@loicdescotte If you have some time to do a review that would be awesome ! 😄

[loicdescotte]

Nice, I think it adds a lot of flexibility.

[loicdescotte]

@Mogztter I've just read the code and it seems great :)

[ggrossetie]

@loicdescotte Thanks for the review
@jroper \o/