bb.net
Class Emailer

java.lang.Object
  extended by bb.net.Emailer
All Implemented Interfaces:
Closeable

public class Emailer
extends Object
implements Closeable

Each instance stores a specific set of mail server resources (see the makeXXX factory method javadocs). It may then be used to send arbitrary emails using one of the send methods.

This class is not multithread safe.

Author:
Brent Boyer
See Also:
"The 2001-10-23 JDC newsletter for tips on JavaMail", javamail javadocs

Nested Class Summary
private static class Emailer.Listener
           
static class Emailer.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  Set<ConnectionListener> connectionListeners
          Set of all ConnectionListeners used by this instance.
private  String from
          Stores the from email address(es) which will be used for all emails sent by this instance.
private static Set<String> keysSmtpSslMandatory
          Set of all mandatory keys for the properties arg of makeForSmtpSsl(bb.util.Properties2).
private static Set<String> keysSmtpSslOptional
          Set of all optional keys for the properties arg of makeForSmtpSsl(bb.util.Properties2).
private static boolean mailDebug_default
          Default value for the "mail.debug" or "mail.smtp.debug" property.
private  boolean parseStrictness
          Specifies the boolean value that will be supplied to InternetAddress.parse(String, boolean) when parsing address Strings (e.g. from, to, cc, and bcc).
private static boolean parseStrictness_default
          Default value for parseStrictness.
private  Session session
          Session used by this instance.
private static String sslFactory_default
          Default value for the "mail.smtp.socketFactory.class" property.
private  Transport transport
          Transport used by this instance.
private  Set<TransportListener> transportListeners
          Set of all TransportListeners used by this instance.
 
Constructor Summary
private Emailer(String from, boolean parseStrictness, Session session)
          Constructor.
 
Method Summary
 boolean addConnectionListener(ConnectionListener connectionListener)
          Attempts to add connectionListener to an internal Set of ConnectionListeners.
 boolean addTransportListener(TransportListener transportListener)
          Attempts to add transportListener to an internal Set of TransportListeners.
 void close()
          Closes all messaging resources currently being used by this instance.
 void initTransport()
          Closes transport if it currently exists.
static Emailer make(File file)
          Returns make( new Properties2(file) ).
static Emailer make(Properties2 properties)
          Inspects the value of the "mail.transport.protocol" key in properties (which must be defined), and then returns the result of calling the appropriate makeXXX method (e.g.
static Emailer makeForSmtpSsl(Properties2 properties)
          Creates a new instance that is configured to use SMTP with SSL.
 boolean removeConnectionListener(ConnectionListener connectionListener)
          Attempts to remove connectionListener from an internal Set of ConnectionListeners.
 boolean removeTransportListener(TransportListener transportListener)
          Attempts to remove transportListener from an internal Set of TransportListeners.
 void send(String subject, String messageBody, String to)
          Convenience method that calls the more general send method with null values for the cc and bcc arguments.
 void send(String subject, String messageBody, String to, String cc, String bcc, Map<String,String> headers)
          This method sends an email using the info in the arguments.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mailDebug_default

private static final boolean mailDebug_default
Default value for the "mail.debug" or "mail.smtp.debug" property.

See Also:
Constant Field Values

parseStrictness_default

private static final boolean parseStrictness_default
Default value for parseStrictness.

See Also:
Constant Field Values

keysSmtpSslMandatory

private static final Set<String> keysSmtpSslMandatory
Set of all mandatory keys for the properties arg of makeForSmtpSsl(bb.util.Properties2). These keys are:

                mail.transport.protocol
                mail.smtp.host
                mail.smtp.port
                username
                password
 


keysSmtpSslOptional

private static final Set<String> keysSmtpSslOptional
Set of all optional keys for the properties arg of makeForSmtpSsl(bb.util.Properties2). If not defined, default values will be supplied. These keys are:

                mail.smtp.debug
                mail.smtp.socketFactory.class
                mail.smtp.socketFactory.port
                mail.smtp.user
                parseStrictness
 


sslFactory_default

private static final String sslFactory_default
Default value for the "mail.smtp.socketFactory.class" property.

See Also:
Constant Field Values

from

private final String from
Stores the from email address(es) which will be used for all emails sent by this instance.

Contract: is never blank.


parseStrictness

private final boolean parseStrictness
Specifies the boolean value that will be supplied to InternetAddress.parse(String, boolean) when parsing address Strings (e.g. from, to, cc, and bcc).


session

private final Session session
Session used by this instance.

Contract: is never null.


transport

private Transport transport
Transport used by this instance.

Contract: is null until initialized by initTransport.


connectionListeners

private final Set<ConnectionListener> connectionListeners
Set of all ConnectionListeners used by this instance.

Contract: is never null.


transportListeners

private final Set<TransportListener> transportListeners
Set of all TransportListeners used by this instance.

Contract: is never null.

Constructor Detail

Emailer

private Emailer(String from,
                boolean parseStrictness,
                Session session)
         throws IllegalArgumentException
Constructor.

Throws:
IllegalArgumentException - if from fails EmailUtil.checkHeaderFieldBody; session is null
Method Detail

make

public static Emailer make(File file)
                    throws RuntimeException,
                           IllegalArgumentException
Returns make( new Properties2(file) ).

Throws:
RuntimeException - if Properties2 has any problem parsing file
IllegalArgumentException - if the properties parsed from file is missing required keys/values, or contains illegal keys

make

public static Emailer make(Properties2 properties)
                    throws IllegalArgumentException
Inspects the value of the "mail.transport.protocol" key in properties (which must be defined), and then returns the result of calling the appropriate makeXXX method (e.g. makeForSmtpSsl).

It is highly recommended that users call this method instead of one of the protocol specific makeXXX methods, because then they can change their email properties files to new protocols, if needed, and not have to change their code.

Throws:
IllegalArgumentException - if properties is null, is missing required keys/values, or contains illegal keys

makeForSmtpSsl

public static Emailer makeForSmtpSsl(Properties2 properties)
                              throws IllegalArgumentException
Creates a new instance that is configured to use SMTP with SSL.

Throws:
IllegalArgumentException - if properties is null, fails to have keys for every element of keysSmtpSslMandatory, contains illegal keys besides those in keysSmtpSslMandatory and keysSmtpSslOptional, or its value for the key mail.transport.protocol is not smtp

initTransport

public void initTransport()
                   throws MessagingException,
                          NoSuchProviderException
Closes transport if it currently exists. Then recreates it from session, adds all listeners (connectionListeners and transportListeners), and connects it.

This method is normally called by send(String, String, String, String, String, Map) in order to lazy initialize transport. However, it may be the case that transport has become invalid (e.g. the mail server may have severed the connection after a while; see this forum posting). So, this method was made public to let users perform error recovery.

Throws:
MessagingException
NoSuchProviderException

addConnectionListener

public boolean addConnectionListener(ConnectionListener connectionListener)
                              throws IllegalArgumentException
Attempts to add connectionListener to an internal Set of ConnectionListeners.

Returns:
true if connectionListener was added by this call, false if was already present
Throws:
IllegalArgumentException - if connectionListener == null

removeConnectionListener

public boolean removeConnectionListener(ConnectionListener connectionListener)
                                 throws IllegalArgumentException
Attempts to remove connectionListener from an internal Set of ConnectionListeners.

Returns:
true if connectionListener was removed by this call, false if was not present
Throws:
IllegalArgumentException - if connectionListener == null

addTransportListener

public boolean addTransportListener(TransportListener transportListener)
                             throws IllegalArgumentException
Attempts to add transportListener to an internal Set of TransportListeners.

Returns:
true if transportListener was added by this call, false if was already present
Throws:
IllegalArgumentException - if transportListener == null

removeTransportListener

public boolean removeTransportListener(TransportListener transportListener)
                                throws IllegalArgumentException
Attempts to remove transportListener from an internal Set of TransportListeners.

Returns:
true if transportListener was removed by this call, false if was not present
Throws:
IllegalArgumentException - if transportListener == null

send

public final void send(String subject,
                       String messageBody,
                       String to)
                throws IllegalArgumentException,
                       MessagingException
Convenience method that calls the more general send method with null values for the cc and bcc arguments.

Throws:
IllegalArgumentException
MessagingException

send

public final void send(String subject,
                       String messageBody,
                       String to,
                       String cc,
                       String bcc,
                       Map<String,String> headers)
                throws IllegalArgumentException,
                       MessagingException
This method sends an email using the info in the arguments.

Warning: the mail server may override the mailhost value to prevent spoofing?

Throws:
IllegalArgumentException - if some arg is illegal
MessagingException - if some messaging error occurs
See Also:
"The program /demo/msgsend.java", All About Email Headers

close

public final void close()
                 throws RuntimeException
Closes all messaging resources currently being used by this instance.

Specified by:
close in interface Closeable
Throws:
RuntimeException - (or some subclass) if any problem occurs