-
-
Notifications
You must be signed in to change notification settings - Fork 271
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
#115: overhauled how Mailers are created and initialized. Everything …
…now works exclusively through builders, including property defaults.
- Loading branch information
Showing
20 changed files
with
1,435 additions
and
1,026 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
284 changes: 284 additions & 0 deletions
284
src/main/java/org/simplejavamail/mailer/MailerBuilder.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,284 @@ | ||
package org.simplejavamail.mailer; | ||
|
||
import org.simplejavamail.mailer.config.TransportStrategy; | ||
|
||
import javax.annotation.Nonnull; | ||
import javax.annotation.Nullable; | ||
import javax.mail.Session; | ||
|
||
import static org.simplejavamail.util.ConfigLoader.Property.SMTP_HOST; | ||
import static org.simplejavamail.util.ConfigLoader.Property.SMTP_PASSWORD; | ||
import static org.simplejavamail.util.ConfigLoader.Property.SMTP_PORT; | ||
import static org.simplejavamail.util.ConfigLoader.Property.SMTP_USERNAME; | ||
import static org.simplejavamail.util.ConfigLoader.Property.TRANSPORT_STRATEGY; | ||
import static org.simplejavamail.util.ConfigLoader.getProperty; | ||
import static org.simplejavamail.util.ConfigLoader.hasProperty; | ||
|
||
/** | ||
* Entry builder used to start a {@link MailerGenericBuiler} and fully configure a Mailer. | ||
* <p> | ||
* Any of these methods return a specialized builder, of which there are two: | ||
* <ul> | ||
* <li>One to configure a Mailer using a custom {@link Session} instance</li> | ||
* <li>One to fully configure a Mailer which will produce its own {@link Session} instance</li> | ||
* </ul> | ||
* | ||
* @see MailerFromSessionBuilder | ||
* @see MailerRegularBuilder | ||
*/ | ||
public class MailerBuilder { | ||
|
||
/** | ||
* Delegates to {@link MailerFromSessionBuilder#usingSession(Session)}. | ||
*/ | ||
public static MailerFromSessionBuilder usingSession(@Nonnull final Session session) { | ||
return new MailerFromSessionBuilder().usingSession(session); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withTransportStrategy(TransportStrategy)}. | ||
*/ | ||
public static MailerRegularBuilder withTransportStrategy(@Nonnull final TransportStrategy transportStrategy) { | ||
return new MailerRegularBuilder().withTransportStrategy(transportStrategy); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServer(ServerConfig)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServer(@Nonnull final ServerConfig serverConfig) { | ||
return new MailerRegularBuilder().withSMTPServer(serverConfig); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServer(String, Integer, String, String)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port, @Nullable final String username, @Nullable final String password) { | ||
return new MailerRegularBuilder().withSMTPServer(host, port, username, password); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServer(String, Integer, String)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port, @Nullable final String username) { | ||
return new MailerRegularBuilder().withSMTPServer(host, port, username); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServer(String, Integer)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port) { | ||
return new MailerRegularBuilder().withSMTPServer(host, port); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServerHost(String)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServerHost(@Nullable final String host) { | ||
return new MailerRegularBuilder().withSMTPServerHost(host); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServerPort(Integer)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServerPort(@Nullable final Integer port) { | ||
return new MailerRegularBuilder().withSMTPServerPort(port); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServerUsername(String)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServerUsername(@Nullable final String username) { | ||
return new MailerRegularBuilder().withSMTPServerUsername(username); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withSMTPServerPassword(String)}. | ||
*/ | ||
public static MailerRegularBuilder withSMTPServerPassword(@Nullable final String password) { | ||
return new MailerRegularBuilder().withSMTPServerPassword(password); | ||
} | ||
|
||
/** | ||
* Delegates to {@link MailerRegularBuilder#withDebugLogging(Boolean)} | ||
* <p> | ||
* <strong>Note:</strong> Assumes you don't want to use your own {@link Session} object (otherwise start with {@link #usingSession(Session)} | ||
* instead). | ||
*/ | ||
public static MailerRegularBuilder withDebugLogging(Boolean debugLogging) { | ||
return new MailerRegularBuilder().withDebugLogging(debugLogging); | ||
} | ||
|
||
/** | ||
* Shortcuts to {@link MailerRegularBuilder#buildMailer()}. This means that none of the builder methods are used and the configuration completely | ||
* depends on defaults being configured from property file ("simplejavamail.properties") on the classpath or through programmatic defaults. | ||
*/ | ||
public static Mailer buildMailer() { | ||
return new MailerRegularBuilder().buildMailer(); | ||
} | ||
|
||
/** | ||
* Default builder for generating Mailer instances. | ||
* <p> | ||
* In addition on generic Mailer setting, this builder is used to configure SMTP server details and transport strategy needed to produce a valid | ||
* {@link Session} instance. | ||
* | ||
* @see TransportStrategy | ||
*/ | ||
public static class MailerRegularBuilder extends MailerGenericBuiler<MailerRegularBuilder> { | ||
|
||
private String host; | ||
private Integer port; | ||
private String username; | ||
private String password; | ||
private TransportStrategy transportStrategy; | ||
|
||
/** | ||
* Sets defaults configured for SMTP host, SMTP port, SMTP username, SMTP password and transport strategy. | ||
* <p> | ||
* <strong>Note:</strong> Any builder methods invoked after this will override the default value. | ||
*/ | ||
MailerRegularBuilder() { | ||
if (hasProperty(SMTP_HOST)) { | ||
withSMTPServerHost((String) getProperty(SMTP_HOST)); | ||
} | ||
if (hasProperty(SMTP_PORT)) { | ||
withSMTPServerPort((Integer) getProperty(SMTP_PORT)); | ||
} | ||
if (hasProperty(SMTP_USERNAME)) { | ||
withSMTPServerUsername((String) getProperty(SMTP_USERNAME)); | ||
} | ||
if (hasProperty(SMTP_PASSWORD)) { | ||
withSMTPServerPassword((String) getProperty(SMTP_PASSWORD)); | ||
} | ||
withTransportStrategy(TransportStrategy.SMTP); | ||
if (hasProperty(TRANSPORT_STRATEGY)) { | ||
withTransportStrategy((TransportStrategy) getProperty(TRANSPORT_STRATEGY)); | ||
} | ||
} | ||
|
||
/** | ||
* Sets the optional transport strategy of this mailer. Will default to {@link TransportStrategy#SMTP} is left empty. | ||
*/ | ||
public MailerRegularBuilder withTransportStrategy(@Nonnull final TransportStrategy transportStrategy) { | ||
this.transportStrategy = transportStrategy; | ||
return this; | ||
} | ||
|
||
/** | ||
* @param host Delegates to {@link #withSMTPServerHost(String)}. | ||
* @param port Delegates to {@link #withSMTPServerPort(Integer)}. | ||
* @param username Delegates to {@link #withSMTPServerUsername(String)}. | ||
* @param password Delegates to {@link #withSMTPServerPassword(String)}. | ||
*/ | ||
public MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port, @Nullable final String username, @Nullable final String password) { | ||
return withSMTPServerHost(host) | ||
.withSMTPServerPort(port) | ||
.withSMTPServerUsername(username) | ||
.withSMTPServerPassword(password); | ||
} | ||
|
||
/** | ||
* @param host Delegates to {@link #withSMTPServerHost(String)}. | ||
* @param port Delegates to {@link #withSMTPServerPort(Integer)}. | ||
* @param username Delegates to {@link #withSMTPServerUsername(String)}. | ||
*/ | ||
public MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port, @Nullable final String username) { | ||
return withSMTPServerHost(host) | ||
.withSMTPServerPort(port) | ||
.withSMTPServerUsername(username); | ||
} | ||
|
||
/** | ||
* @param host Delegates to {@link #withSMTPServerHost(String)}. | ||
* @param port Delegates to {@link #withSMTPServerPort(Integer)}. | ||
*/ | ||
public MailerRegularBuilder withSMTPServer(@Nullable final String host, @Nullable final Integer port) { | ||
return withSMTPServerHost(host) | ||
.withSMTPServerPort(port); | ||
} | ||
|
||
/** | ||
* Delegates for each contained property respectively to: | ||
* <ul> | ||
* <li>{@link #withSMTPServerHost(String)}</li> | ||
* <li>{@link #withSMTPServerPort(Integer)}</li> | ||
* <li>{@link #withSMTPServerUsername(String)}</li> | ||
* <li>{@link #withSMTPServerPassword(String)}</li> | ||
* </ul> | ||
*/ | ||
public MailerRegularBuilder withSMTPServer(@Nonnull final ServerConfig serverConfig) { | ||
return withSMTPServerHost(serverConfig.getHost()) | ||
.withSMTPServerPort(serverConfig.getPort()) | ||
.withSMTPServerUsername(serverConfig.getUsername()) | ||
.withSMTPServerPassword(serverConfig.getPassword()); | ||
} | ||
|
||
/** | ||
* Sets the optional SMTP host. Will default to pre-configured property if left empty. | ||
*/ | ||
public MailerRegularBuilder withSMTPServerHost(@Nullable final String host) { | ||
this.host = host; | ||
return this; | ||
} | ||
|
||
/** | ||
* Sets the optional SMTP port. Will default to pre-configured property if left empty. | ||
*/ | ||
public MailerRegularBuilder withSMTPServerPort(@Nullable final Integer port) { | ||
this.port = port; | ||
return this; | ||
} | ||
|
||
/** | ||
* Sets the optional SMTP username. Will default to pre-configured property if left empty. | ||
*/ | ||
public MailerRegularBuilder withSMTPServerUsername(@Nullable final String username) { | ||
this.username = username; | ||
return this; | ||
} | ||
|
||
/** | ||
* Sets the optional SMTP password. Will default to pre-configured property if left empty. | ||
*/ | ||
public MailerRegularBuilder withSMTPServerPassword(@Nullable final String password) { | ||
this.password = password; | ||
return this; | ||
} | ||
|
||
/** | ||
* Builds the actual {@link Mailer} instance with everything configured on this builder instance. | ||
* <p> | ||
* For all configurable values: if omitted, a default value will be attempted by looking at property files or manually defined defauls. | ||
*/ | ||
public Mailer buildMailer() { | ||
return new Mailer(this); | ||
} | ||
|
||
/** | ||
* For internal use. | ||
*/ | ||
ServerConfig buildServerConfig() { | ||
return new ServerConfig(getHost(), getPort(), getUsername(), getPassword()); | ||
} | ||
|
||
public String getHost() { | ||
return host; | ||
} | ||
|
||
public Integer getPort() { | ||
return port; | ||
} | ||
|
||
public String getUsername() { | ||
return username; | ||
} | ||
|
||
public String getPassword() { | ||
return password; | ||
} | ||
|
||
public TransportStrategy getTransportStrategy() { | ||
return transportStrategy; | ||
} | ||
} | ||
} |
51 changes: 51 additions & 0 deletions
51
src/main/java/org/simplejavamail/mailer/MailerFromSessionBuilder.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
package org.simplejavamail.mailer; | ||
|
||
import javax.annotation.Nonnull; | ||
import javax.mail.Message; | ||
import javax.mail.Session; | ||
|
||
/** | ||
* Builder that supports a fixed {@link Session} instance. Allows configuring all generic Mailer settings, but not SMTP and transport strategy | ||
* details. | ||
* <p> | ||
* <strong>Note:</strong> Any SMTP server properties that can be set on the {@link Session} object by are presumed to be already present in the passed | ||
* {@link Session} instance. | ||
* | ||
* @see org.simplejavamail.mailer.config.TransportStrategy | ||
*/ | ||
public class MailerFromSessionBuilder extends MailerGenericBuiler<MailerFromSessionBuilder> { | ||
|
||
/** | ||
* @see #usingSession(Session) | ||
*/ | ||
private Session session; | ||
|
||
/** | ||
* Only use this API if you <em>must</em> use your own {@link Session} instance. Assumes that all properties (except session timeout) used to make | ||
* a connection are configured (host, port, authentication and transport protocol settings). | ||
* <p> | ||
* Only proxy can be configured optionally and general connection settings. | ||
* | ||
* @param session A mostly preconfigured mail {@link Session} object with which a {@link Message} can be produced. | ||
*/ | ||
public MailerFromSessionBuilder usingSession(@Nonnull final Session session) { | ||
this.session = session; | ||
return this; | ||
} | ||
|
||
/** | ||
* Builds the actual {@link Mailer} instance with everything configured on this builder instance. | ||
* <p> | ||
* For all configurable values: if omitted, a default value will be attempted by looking at property files or manually defined defauls. | ||
*/ | ||
public Mailer buildMailer() { | ||
return new Mailer(this); | ||
} | ||
|
||
/** | ||
* @see #usingSession(Session) | ||
*/ | ||
public Session getSession() { | ||
return session; | ||
} | ||
} |
Oops, something went wrong.