org.norther.tammi.core.mail
Interface MailSender

All Superinterfaces:

Configurable, Executable, Runnable, Startable

All Known Implementing Classes:

DefaultMailSender

public interface MailSender
extends Executable, Configurable

An interface to send mail. This interface wraps JavaMail(TM) API with simple send mail functionality. Sending mail is asynchronous and calling sendMail() method succeeds if a MIME message can be instantiated and filled with data even though actual sending may fail due to various reasons, for instance server or network failure.

Sender and receiver addresses are handled according to RFC822

The service can be configured with JavaMail API environment settings and some complementary properties. A new session is instantiated each time the settings are modified. The settings may be collected to a property file using the following syntax (all session related properties with a mail prefix are passed to the Session instance as such):

 ##
 # JavaMail standard properties start with the 'mail' suffix.
 ##
 # Transport protocol.
 # mail.transport.protocol = 'protocol'
 ##
 # A general host.
 # mail.host = 'host name'
 ##
 # A protocol specific host.
 # mail.'protocol'.host = 'host name'
 ##
 # A general port number.
 # mail.port = 'port number'
 ##
 # A protocol specific port number.
 # mail.'protocol'.port = 'port number'
 ##
 # A general username.
 # mail.user = 'username'
 ##
 # A protocol specific username.
 # mail.'protocol'.user = 'username'
 ##
 # The return address of the user sending mail in the header information.
 # mail.from = 'user address'
 ##
 # Debug mode setting, defaults to false.
 # mail.debug = true
 ##
 # Default encoding for mail content.
 # mail.mime.charset = 'charset'
 ##
 # Indicates whether strict parsing is required, defaults to true.
 # mail.mime.address.strict = false
 ##
 # Client application name in the X-Mailer header, defaults to 'Tammi Server'.
 # mailsender.x.mailer = 'client name'
 ##
 # General user password for the mail server connection.
 # mailsender.password = 'password'
 ##
 # Protocol specific user password for the mail server connection.
 # mailsender.'protocol'.password = 'password'
 

Host URL address can also be configured as an URL with the following format: 'protocol:'//'user':'password'@'host':'port', these parts (including their delimiters) being optional: password, user:password, port.

Examples: smtp://mail.norther.org
smtp://user@mail.norther.org

Host addresses (URLs) are handled according to the scheme part of the URL string as specified in RFC1738

SMTP is currently the only supported protocol for sending by JavaMail (version 1.3).

Note that there are other ways to authorize users that are not part of SMTP protocol itself. These alternate methods (relaying e.g. on POP3) are currently not supported by this interface.

Author:

Jari Petays, Marketta Priha

See Also:

JavaMail(TM) API

Field Summary

static String	MAIL_DEBUG_PROPERTY The debug session property.
static String	MAIL_FROM_PROPERTY The mail from property.
static String	MAIL_HOST_PROPERTY The host property.
static String	MAIL_MIME_ADDRESS_STRICT_PROPERTY Since 1.3.
static String	MAIL_MIME_CHARSET_PROPERTY Since 1.3.
static String	MAIL_PORT_PROPERTY The port number property not defined in the JavaMail 1.2 spec nor in 1.3 modifications but described in the API documentation.
static String	MAIL_PROPERTY_PREFIX The mail property prefix.
static String	MAIL_TRANSPORT_PROTOCOL_PROPERTY The transport protocol property.
static String	MAIL_USER_PROPERTY The user property.
static String	MAILSENDER_PASSWORD_PROPERTY The password property not defined in the JavaMail 1.2 spec nor in 1.3 modifications.
static String	MAILSENDER_PROPERTY_PREFIX The mail sender property prefix.
static String	MAILSENDER_X_MAILER_PROPERTY The X-Mailer header property.

Method Summary

void	applyServerURL(String server) Applies the specified URL to the mail server configuration.
boolean	getDebug() Gets debugging flag for JavaMail Session object.
javax.mail.internet.InternetAddress	getFrom() Gets the address of the current user.
String	getHost() Gets the host name of the mail server.
int	getPort() Gets the port number of the mail server.
String	getProtocol() Gets the protocol for sending.
String	getServerURL() Gets the mail server to be connected as an URL.
String	getUser() Gets the username for connecting the mail server.
void	sendMail(javax.mail.internet.InternetAddress[] toAddress, String subject, String messageBody) Sends a text-only mail message with minimal addressing information to specified addresses.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress[] replyToAddress, javax.mail.internet.InternetAddress senderAddress, javax.mail.internet.InternetAddress[] toAddress, javax.mail.internet.InternetAddress[] ccAddress, javax.mail.internet.InternetAddress[] bccAddress, String subject, String messageBody) Sends a text-only mail message with full addressing information.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress[] replyToAddress, javax.mail.internet.InternetAddress senderAddress, javax.mail.internet.InternetAddress[] toAddress, javax.mail.internet.InternetAddress[] ccAddress, javax.mail.internet.InternetAddress[] bccAddress, String subject, String messageBody, String encoding) Sends an encoded text-only mail message with full addressing information.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress[] toAddress, String subject, String messageBody) Sends a text-only mail message with less addressing information to specified addresses.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress[] toAddress, String subject, String messageBody, String encoding) Sends an encoded text-only mail message with less addressing information to specified addresses.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress toAddress, String subject, String messageBody) Sends a text-only mail message with less addressing information to the specified addresses.
void	sendMail(javax.mail.internet.InternetAddress fromAddress, javax.mail.internet.InternetAddress toAddress, String subject, String messageBody, String encoding) Sends an encoded text-only mail message with less addressing information to the specified address.
void	sendMail(javax.mail.internet.InternetAddress toAddress, String subject, String messageBody) Sends a text-only mail message with minimal addressing information to the specified address.
void	setDebug(boolean debug) Sets debugging flag for JavaMail Session object.
void	setFrom(javax.mail.internet.InternetAddress from) Sets the address of the current user.
void	setHost(String host) Sets the host name of the mail server.
void	setHost(String host, String protocol) Sets the protocol specific host name of the mail server.
void	setPassword(String password) Sets the password for connecting the mail server.
void	setPassword(String password, String protocol) Sets the protocol specific password for connecting the mail server.
void	setPort(int port) Sets the port number of the mail server.
void	setPort(int port, String protocol) Sets the protocol specific port number of the mail server.
void	setProtocol(String protocol) Sets the protocol for sending.
void	setUser(String user) Sets the username for connecting the mail server.
void	setUser(String user, String protocol) Sets the protocol specific username for connecting the mail server.

Methods inherited from interface org.norther.tammi.core.thread.Executable

getExecutorName, setExecutorName

Methods inherited from interface org.norther.tammi.core.base.Startable

isStarted, start, stop

Methods inherited from interface java.lang.Runnable

run

Methods inherited from interface org.norther.tammi.core.config.Configurable

addProperty, addProperty, clearProperties, containsProperty, getConfigKey, getProperties, getProperty, getPropertyFilePath, indexOfProperty, propertyMap, propertyMap, removeProperty, removeProperty, setConfigKey, setProperties, setProperty, setPropertyFilePath, setPropertyFilePath, storeProperties

Field Detail

MAIL_PROPERTY_PREFIX

static final String MAIL_PROPERTY_PREFIX

The mail property prefix.

See Also:

Constant Field Values

MAIL_TRANSPORT_PROTOCOL_PROPERTY

static final String MAIL_TRANSPORT_PROTOCOL_PROPERTY

The transport protocol property.

See Also:

Constant Field Values

MAIL_HOST_PROPERTY

static final String MAIL_HOST_PROPERTY

The host property.

See Also:

Constant Field Values

MAIL_PORT_PROPERTY

static final String MAIL_PORT_PROPERTY

The port number property not defined in the JavaMail 1.2 spec nor in 1.3 modifications but described in the API documentation.

See Also:

Constant Field Values

MAIL_USER_PROPERTY

static final String MAIL_USER_PROPERTY

The user property.

See Also:

Constant Field Values

MAIL_FROM_PROPERTY

static final String MAIL_FROM_PROPERTY

The mail from property.

See Also:

Constant Field Values

MAIL_DEBUG_PROPERTY

static final String MAIL_DEBUG_PROPERTY

The debug session property.

See Also:

Constant Field Values

MAIL_MIME_CHARSET_PROPERTY

static final String MAIL_MIME_CHARSET_PROPERTY

Since 1.3. The default charset to be used by JavaMail. If not set, the standard J2SE "file.encoding" System property is used. Used when forming the MIME message.

See Also:

Constant Field Values

MAIL_MIME_ADDRESS_STRICT_PROPERTY

static final String MAIL_MIME_ADDRESS_STRICT_PROPERTY

Since 1.3. The "mail.mime.address.strict" property will control the strict flag passed to the parseHeader (in our implementation InternetAddress.parse) method. The default is true.

See Also:

Constant Field Values

MAILSENDER_PROPERTY_PREFIX

static final String MAILSENDER_PROPERTY_PREFIX

The mail sender property prefix.

See Also:

Constant Field Values

MAILSENDER_PASSWORD_PROPERTY

static final String MAILSENDER_PASSWORD_PROPERTY

The password property not defined in the JavaMail 1.2 spec nor in 1.3 modifications.

See Also:

Constant Field Values

MAILSENDER_X_MAILER_PROPERTY

static final String MAILSENDER_X_MAILER_PROPERTY

The X-Mailer header property. The header is typically used to define the client software responsible for generating the mail message.

See Also:

Constant Field Values

Method Detail

getProtocol

String getProtocol()

Gets the protocol for sending.

Returns:

the protocol e.g. 'SMTP'.

setProtocol

void setProtocol(String protocol)

Sets the protocol for sending.

Parameters:

protocol - the protocol e.g. 'SMTP'.

getHost

String getHost()

Gets the host name of the mail server.

Returns:

the host name.

setHost

void setHost(String host)

Sets the host name of the mail server.

Parameters:

host - the host name.

setHost

void setHost(String host,
             String protocol)

Sets the protocol specific host name of the mail server.

Parameters:

host - the host name.

protocol - the protocol.

getPort

int getPort()

Gets the port number of the mail server.

Returns:

the port number.

setPort

void setPort(int port)

Sets the port number of the mail server.

Parameters:

port - the port number.

setPort

void setPort(int port,
             String protocol)

Sets the protocol specific port number of the mail server.

Parameters:

port - the port number.

protocol - the protocol.

getUser

String getUser()

Gets the username for connecting the mail server.

Returns:

the username.

setUser

void setUser(String user)

Sets the username for connecting the mail server.

Parameters:

user - the username.

setUser

void setUser(String user,
             String protocol)

Sets the protocol specific username for connecting the mail server.

Parameters:

user - the username.

protocol - the protocol.

setPassword

void setPassword(String password)

Sets the password for connecting the mail server.

Parameters:

password - the password.

setPassword

void setPassword(String password,
                 String protocol)

Sets the protocol specific password for connecting the mail server.

Parameters:

password - the password.

protocol - the protocol.

getFrom

javax.mail.internet.InternetAddress getFrom()

Gets the address of the current user. Used by the InternetAddress.getLocalAddress method to specify the current user's email, default username@host.

Returns:

the user mail address.

setFrom

void setFrom(javax.mail.internet.InternetAddress from)

Sets the address of the current user. Used by the InternetAddress.getLocalAddress method to specify the current user's email, default username@host.

Parameters:

from - the user mail address.

getDebug

boolean getDebug()

Gets debugging flag for JavaMail Session object.

Returns:

the debug flag.

setDebug

void setDebug(boolean debug)

Sets debugging flag for JavaMail Session object.

Parameters:

debug - the debug flag.

getServerURL

String getServerURL()

Gets the mail server to be connected as an URL. A possible password information is hidden.

Returns:

the URL of the mail server to be connected as a string.

applyServerURL

void applyServerURL(String server)

Applies the specified URL to the mail server configuration.

If null is given, initializes both the protocol specific and general settings.

Parameters:

server - the URL of the mail server to be connected as a string.

sendMail

void sendMail(javax.mail.internet.InternetAddress toAddress,
              String subject,
              String messageBody)
              throws LogException

Sends a text-only mail message with minimal addressing information to the specified address. The 'mail.from' property must have been set.

Parameters:

toAddress - the receiver's mail address.

subject - the subject of the mail.

messageBody - the mail body as text.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress[] toAddress,
              String subject,
              String messageBody)
              throws LogException

Sends a text-only mail message with minimal addressing information to specified addresses. The 'mail.from' property must have been set.

Parameters:

toAddress - the receivers' mail addresses.

subject - the subject of the mail.

messageBody - the mail body as text.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress toAddress,
              String subject,
              String messageBody)
              throws LogException

Sends a text-only mail message with less addressing information to the specified addresses.

Parameters:

fromAddress - the sender's mail address.

toAddress - the receiver's mail address.

subject - the subject of the mail.

messageBody - the mail body as text.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress[] toAddress,
              String subject,
              String messageBody)
              throws LogException

Sends a text-only mail message with less addressing information to specified addresses.

Parameters:

fromAddress - the sender's mail address.

toAddress - the receivers' mail addresses.

subject - the subject of the mail.

messageBody - the mail body as text.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress toAddress,
              String subject,
              String messageBody,
              String encoding)
              throws LogException

Sends an encoded text-only mail message with less addressing information to the specified address.

Parameters:

fromAddress - the sender's mail address.

toAddress - the receiver's mail address.

subject - the subject of the mail.

messageBody - the mail body as text.

encoding - the charset to be applied.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress[] toAddress,
              String subject,
              String messageBody,
              String encoding)
              throws LogException

Sends an encoded text-only mail message with less addressing information to specified addresses.

Parameters:

fromAddress - the sender's mail address.

toAddress - the receivers' mail addresses.

subject - the subject of the mail.

messageBody - the mail body as text.

encoding - the charset to be applied.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress[] replyToAddress,
              javax.mail.internet.InternetAddress senderAddress,
              javax.mail.internet.InternetAddress[] toAddress,
              javax.mail.internet.InternetAddress[] ccAddress,
              javax.mail.internet.InternetAddress[] bccAddress,
              String subject,
              String messageBody)
              throws LogException

Sends a text-only mail message with full addressing information.

Parameters:

fromAddress - the sender's mail address.

replyToAddress - reply to addresses (see RFC822 for details).

senderAddress - sender addresses (see RFC822 for details).

toAddress - the receivers' mail addresses.

ccAddress - the addresses to receive carbon copy of this message.

bccAddress - the addresses to receive blind carbon copy of this message.

subject - the subject of the mail.

messageBody - the mail body as text.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.

sendMail

void sendMail(javax.mail.internet.InternetAddress fromAddress,
              javax.mail.internet.InternetAddress[] replyToAddress,
              javax.mail.internet.InternetAddress senderAddress,
              javax.mail.internet.InternetAddress[] toAddress,
              javax.mail.internet.InternetAddress[] ccAddress,
              javax.mail.internet.InternetAddress[] bccAddress,
              String subject,
              String messageBody,
              String encoding)
              throws LogException

Sends an encoded text-only mail message with full addressing information.

Parameters:

fromAddress - the sender's mail address.

replyToAddress - reply to addresses (see RFC822 for details).

senderAddress - sender addresses (see RFC822 for details).

toAddress - the receivers' mail addresses.

ccAddress - the addresses to receive carbon copy of this message.

bccAddress - the addresses to receive blind carbon copy of this message.

subject - the subject of the mail.

messageBody - the mail body as text.

encoding - the charset to be applied.

Throws:

LogException - if the addresses cannot be parsed or other problems in setting the data.