er.javamail
Class ERJavaMail

java.lang.Object
  er.extensions.ERXFrameworkPrincipal
      er.javamail.ERJavaMail

public class ERJavaMail
extends ERXFrameworkPrincipal

ERJavaMail is the principal class for the ERJavaMail framework.

Author:

Camille Troillard, Max Muller

Properties

er.javamail.centralize	er.javamail.centralize
er.javamail.adminEmail	er.javamail.adminEmail
er.javamail.debugEnabled	er.javamail.debugEnabled
er.javamail.senderQueue.size	er.javamail.senderQueue.size
er.javamail.milliSecondsWaitIfSenderOverflowed	er.javamail.milliSecondsWaitIfSenderOverflowed
er.javamail.XMailerHeader	er.javamail.XMailerHeader
er.javamail.smtpProtocol	er.javamail.smtpProtocol
er.javamail.smtpHost	er.javamail.smtpHost
mail.[smtpProtocol].host	mail.[smtpProtocol].host
WOSMTPHost	WOSMTPHost
er.javamail.smtpPort	er.javamail.smtpPort
mail.[smtpProtocol].port	mail.[smtpProtocol].port
er.javamail.smtpAuth	er.javamail.smtpAuth
mail.[smtpProtocol].auth	mail.[smtpProtocol].auth
er.javamail.smtpUser	er.javamail.smtpUser
mail.[smtpProtocol].user	mail.[smtpProtocol].user
er.javamail.smtpPassword	er.javamail.smtpPassword
mail.[smtpProtocol].password	mail.[smtpProtocol].password
mail.smtps.socketFactory.fallback	mail.smtps.socketFactory.fallback
er.javamail.emailPattern	er.javamail.emailPattern
er.javamail.WhiteListEmailAddressPatterns	er.javamail.WhiteListEmailAddressPatterns
er.javamail.BlackListEmailAddressPatterns	er.javamail.BlackListEmailAddressPatterns

Nested Class Summary

static interface

ERJavaMail.Delegate

Nested classes/interfaces inherited from class er.extensions.ERXFrameworkPrincipal

ERXFrameworkPrincipal.Observer

Field Summary

protected java.lang.String	_adminEmail email address used when centralizeMails == true Needed when debugging application so that mails are always sent to only one destination.
protected boolean	_centralize Used to send mail to adminEmail only.
protected boolean	_debugEnabled This property specify wether JavaMail is debug enabled or not.
protected javax.mail.Session	_defaultSession This is the default JavaMail Session.
protected java.lang.String	_defaultXMailerHeader This property sets the default header for the X-Mailer property
protected int	_milliSecondsWaitIfSenderOverflowed Wait n milliseconds (by default this value is 6000) if the mail sender is overflowed
protected java.util.regex.Pattern	_pattern The compiled form of the EMAIL_VALIDATION_PATTERN pattern.
protected int	_senderQueueSize Number of messages that the sender queue can hold at a time; default to 50 messages and can be configured by er.javamail.senderQueue.size system property.
protected com.webobjects.eocontrol.EOOrQualifier	blackListQualifier holds the black list qualifier
protected com.webobjects.foundation.NSArray<java.lang.String>	blakListEmailAddressPatterns holds the array of black list email addresses
static java.lang.Class<?>[]	REQUIRES
protected static ERJavaMail	sharedInstance ERJavaMail class singleton.
protected com.webobjects.foundation.NSArray<java.lang.String>	whiteListEmailAddressPatterns holds the array of white list email addresses
protected com.webobjects.eocontrol.EOOrQualifier	whiteListQualifier holds the white list qualifier

Fields inherited from class er.extensions.ERXFrameworkPrincipal

initializedFrameworks, launchingFrameworks

Constructor Summary

ERJavaMail()

Method Summary

java.lang.String	adminEmail() admin email accessor.
com.webobjects.foundation.NSArray<java.lang.String>	blackListEmailAddressPatterns() Gets the array of black list email address patterns.
com.webobjects.eocontrol.EOOrQualifier	blackListQualifier() Gets the Or qualifier to match any of the patterns in the black list.
boolean	centralize() Centralize is used to send all the outbound email to a single address which is useful when debugging.
boolean	debugEnabled() Returns true if JavaMail is debug enabled.
javax.mail.Session	defaultSession() This is the deafult JavaMail Session accessor.
java.lang.String	defaultXMailerHeader() Gets the default X-Mailer header to use for sending mails.
com.webobjects.foundation.NSArray<java.lang.String>	filterEmailAddresses(com.webobjects.foundation.NSArray<java.lang.String> emailAddresses) Filters an array of email addresses by the black and white lists.
void	finishInitialization() Specialized implementation of the method from ERXPrincipalClass.
boolean	hasBlackList() Determines if a black list has been specified
boolean	hasWhiteList() Determines if a white list has been specified
void	initializeFrameworkFromSystemProperties() This method is used to initialize ERJavaMail from System properties.
boolean	isValidEmail(java.lang.String email) Predicate used to validate email well-formness.
int	milliSecondsWaitIfSenderOverflowed() This method return the time spent waiting if the mail queue if overflowed.
javax.mail.Session	newSession() Returns a newly allocated Session object from the System Properties
javax.mail.Session	newSession(java.util.Properties props) Returns a newly allocated Session object from the given Properties
javax.mail.Session	newSessionForContext(java.util.Properties properties, java.lang.String contextString) Returns a newly allocated Session object from the given Properties
protected javax.mail.Session	newSessionForContext(java.lang.String contextString) Returns a new Session object that is appropriate for the given context.
javax.mail.Session	newSessionForMessage(ERMessage message) Returns a newly allocated Session object for the given message.
protected com.webobjects.eocontrol.EOOrQualifier	qualifierArrayForEmailPatterns(com.webobjects.foundation.NSArray<java.lang.String> emailPatterns) Constructs an Or qualifier for filtering an array of strings that might have the * wildcard character.
int	senderQueueSize()
protected javax.mail.Session	sessionForContext(java.lang.String contextString) Returns the Session object that is appropriate for the given context.
javax.mail.Session	sessionForMessage(ERMessage message) Returns the Session object that is appropriate for the given message.
void	setAdminEmail(java.lang.String adminEmail) Sets the admin email to another value.
void	setCentralize(boolean centralize) Sets the value of the er.javamail.centralize Property.
void	setDebugEnabled(boolean debug) Sets the debug mode of JavaMail.
void	setDefaultSession(javax.mail.Session session) Sets the default JavaMail session to a particular value.
void	setDefaultXMailerHeader(java.lang.String header) Sets the default value of the XMailer header used when sending mails.
void	setDelegate(ERJavaMail.Delegate delegate)
void	setMilliSecondsWaitIfSenderOverflowed(int value) Sets the value of the er.javamail.milliSecondsWaitIfSenderOverflowed Property.
void	setSenderQueueSize(int value)
protected void	setupSmtpHostSafely() Helper method to init the smtpHost property.
protected void	setupSmtpProperties(java.util.Properties properties, java.lang.String contextString)
static ERJavaMail	sharedInstance() Accessor to the ERJavaMail singleton.
java.lang.String	smtpProtocolForContext(java.lang.String contextString) Returns the SMTP protocol to use for connections.
java.lang.String	validateEmail(com.webobjects.eocontrol.EOEnterpriseObject object, java.lang.String key, java.lang.String email) Validates an enterprise object's email attribute (accessed via key).
com.webobjects.foundation.NSArray<java.lang.String>	whiteListEmailAddressPatterns() Gets the array of white list email address patterns.
com.webobjects.eocontrol.EOOrQualifier	whiteListQualifier() Whilte list Or qualifier to match any of the patterns in the white list.

Methods inherited from class er.extensions.ERXFrameworkPrincipal

didFinishInitialization, initialize, setUpFrameworkPrincipalClass, sharedInstance, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

REQUIRES

public static final java.lang.Class<?>[] REQUIRES

sharedInstance

protected static ERJavaMail sharedInstance

ERJavaMail class singleton.

_pattern

protected java.util.regex.Pattern _pattern

The compiled form of the EMAIL_VALIDATION_PATTERN pattern.

_defaultSession

protected javax.mail.Session _defaultSession

This is the default JavaMail Session. It is shared among all deliverers for immediate deliveries. Deferred deliverers, use their own JavaMail session.

_adminEmail

protected java.lang.String _adminEmail

email address used when centralizeMails == true
Needed when debugging application so that mails are always sent to only one destination.

_debugEnabled

protected boolean _debugEnabled

This property specify wether JavaMail is debug enabled or not.

_defaultXMailerHeader

protected java.lang.String _defaultXMailerHeader

This property sets the default header for the X-Mailer property

_centralize

protected boolean _centralize

Used to send mail to adminEmail only. Useful for debugging issues

_senderQueueSize

protected int _senderQueueSize

Number of messages that the sender queue can hold at a time; default to 50 messages and can be configured by er.javamail.senderQueue.size system property.

_milliSecondsWaitIfSenderOverflowed

protected int _milliSecondsWaitIfSenderOverflowed

Wait n milliseconds (by default this value is 6000) if the mail sender is overflowed

whiteListEmailAddressPatterns

protected com.webobjects.foundation.NSArray<java.lang.String> whiteListEmailAddressPatterns

holds the array of white list email addresses

blakListEmailAddressPatterns

protected com.webobjects.foundation.NSArray<java.lang.String> blakListEmailAddressPatterns

holds the array of black list email addresses

whiteListQualifier

protected com.webobjects.eocontrol.EOOrQualifier whiteListQualifier

holds the white list qualifier

blackListQualifier

protected com.webobjects.eocontrol.EOOrQualifier blackListQualifier

holds the black list qualifier

Constructor Detail

ERJavaMail

public ERJavaMail()

Method Detail

sharedInstance

public static ERJavaMail sharedInstance()

Accessor to the ERJavaMail singleton.

Returns:

the one ERJavaMail instance

setDelegate

public void setDelegate(ERJavaMail.Delegate delegate)

finishInitialization

public void finishInitialization()

Specialized implementation of the method from ERXPrincipalClass.

Specified by:

finishInitialization in class ERXFrameworkPrincipal

initializeFrameworkFromSystemProperties

public void initializeFrameworkFromSystemProperties()

This method is used to initialize ERJavaMail from System properties. Later, we will implement a way to initialize those properties everytime the propertis are changed. The observer will call this method whenever appropriate.

setupSmtpHostSafely

protected void setupSmtpHostSafely()

Helper method to init the smtpHost property. This method first check is er.javamail.smtpHost is set. If it is not set, then it looks for mail.smtp.host (standard JavaMail property) and finally the WOSMTPHost property. When a correct property is found, then it sets both properties to the found value. If no properties are found, a RuntimeException is thrown.

Throws:

java.lang.RuntimeException - if neither one of er.javamail.smtpHost, mail.smtp.host or WOSMTPHost is set.

setupSmtpProperties

protected void setupSmtpProperties(java.util.Properties properties,
                                   java.lang.String contextString)

setDefaultSession

public void setDefaultSession(javax.mail.Session session)

Sets the default JavaMail session to a particular value. This value is set by default at initialization of the framework but you can specify a custom one by using this method. Note that a new deliverer need to be instanciated for changes to be taken in account.

Parameters:

session - the default javax.mail.Session

defaultSession

public javax.mail.Session defaultSession()

This is the deafult JavaMail Session accessor. It is shared among all deliverers for immediate deliveries. Deferred deliverers, use their own JavaMail session.

Returns:

the default javax.mail.Session instance

newSession

public javax.mail.Session newSession(java.util.Properties props)

Returns a newly allocated Session object from the given Properties

Parameters:

props - a Properties value

Returns:

a javax.mail.Session value initialized from the given properties

newSession

public javax.mail.Session newSession()

Returns a newly allocated Session object from the System Properties

Returns:

a javax.mail.Session value

newSessionForMessage

public javax.mail.Session newSessionForMessage(ERMessage message)

Returns a newly allocated Session object for the given message.

Parameters:

message - the message

Returns:

a new javax.mail.Session value

sessionForMessage

public javax.mail.Session sessionForMessage(ERMessage message)

Returns the Session object that is appropriate for the given message.

Returns:

a javax.mail.Session value

newSessionForContext

protected javax.mail.Session newSessionForContext(java.lang.String contextString)

Returns a new Session object that is appropriate for the given context.

Parameters:

contextString - the message context

Returns:

a new javax.mail.Session value

newSessionForContext

public javax.mail.Session newSessionForContext(java.util.Properties properties,
                                               java.lang.String contextString)

Returns a newly allocated Session object from the given Properties

Parameters:

properties - a Properties value

Returns:

a javax.mail.Session value initialized from the given properties

sessionForContext

protected javax.mail.Session sessionForContext(java.lang.String contextString)

Returns the Session object that is appropriate for the given context.

Parameters:

contextString - the message context

Returns:

a javax.mail.Session value

adminEmail

public java.lang.String adminEmail()

admin email accessor. The admin email is the email address where centralized mail go to.

Returns:

a String value

setAdminEmail

public void setAdminEmail(java.lang.String adminEmail)

Sets the admin email to another value. This value is set at initialization from the er.javamail.adminEmail Property.

Parameters:

adminEmail - a String value

debugEnabled

public boolean debugEnabled()

Returns true if JavaMail is debug enabled.

Returns:

a boolean value

setDebugEnabled

public void setDebugEnabled(boolean debug)

Sets the debug mode of JavaMail.

Parameters:

debug - a boolean value sets JavaMail in debug mode

defaultXMailerHeader

public java.lang.String defaultXMailerHeader()

Gets the default X-Mailer header to use for sending mails. Pulls the value out of the property: er.javamail.XMailerHeader

Returns:

default X-Mailer header

setDefaultXMailerHeader

public void setDefaultXMailerHeader(java.lang.String header)

Sets the default value of the XMailer header used when sending mails.

Parameters:

header - a String value

centralize

public boolean centralize()

Centralize is used to send all the outbound email to a single address which is useful when debugging.

Returns:

a boolean value

setCentralize

public void setCentralize(boolean centralize)

Sets the value of the er.javamail.centralize Property.

Parameters:

centralize - if the boolean value is true, then all the outbound mails will be sent to adminEmail email address.

smtpProtocolForContext

public java.lang.String smtpProtocolForContext(java.lang.String contextString)

Returns the SMTP protocol to use for connections.

senderQueueSize

public int senderQueueSize()

setSenderQueueSize

public void setSenderQueueSize(int value)

milliSecondsWaitIfSenderOverflowed

public int milliSecondsWaitIfSenderOverflowed()

This method return the time spent waiting if the mail queue if overflowed. During that time, mails are sent and the queue lowers. When the duration is spent, and the queue is under the overflow limit, the mails are being sent again.

Returns:

an int value

setMilliSecondsWaitIfSenderOverflowed

public void setMilliSecondsWaitIfSenderOverflowed(int value)

Sets the value of the er.javamail.milliSecondsWaitIfSenderOverflowed Property.

Parameters:

value - an int value in milli-seconds.

validateEmail

public java.lang.String validateEmail(com.webobjects.eocontrol.EOEnterpriseObject object,
                                      java.lang.String key,
                                      java.lang.String email)

Validates an enterprise object's email attribute (accessed via key).

Parameters:

object - the object to be validated

key - the attribute's name

email - the email value

Returns:

the email if the validation didn't failed

isValidEmail

public boolean isValidEmail(java.lang.String email)

Predicate used to validate email well-formness.

Parameters:

email - the email String value to validate

Returns:

true if the email is valid

hasWhiteList

public boolean hasWhiteList()

Determines if a white list has been specified

Returns:

if the white list has any elements in it

hasBlackList

public boolean hasBlackList()

Determines if a black list has been specified

Returns:

if the black list has any elements in it

whiteListEmailAddressPatterns

public com.webobjects.foundation.NSArray<java.lang.String> whiteListEmailAddressPatterns()

Gets the array of white list email address patterns.

Returns:

array of white list email address patterns

blackListEmailAddressPatterns

public com.webobjects.foundation.NSArray<java.lang.String> blackListEmailAddressPatterns()

Gets the array of black list email address patterns.

Returns:

array of black list email address patterns

whiteListQualifier

public com.webobjects.eocontrol.EOOrQualifier whiteListQualifier()

Whilte list Or qualifier to match any of the patterns in the white list.

Returns:

Or qualifier for the white list

blackListQualifier

public com.webobjects.eocontrol.EOOrQualifier blackListQualifier()

Gets the Or qualifier to match any of the patterns in the black list.

Returns:

or qualifier

qualifierArrayForEmailPatterns

protected com.webobjects.eocontrol.EOOrQualifier qualifierArrayForEmailPatterns(com.webobjects.foundation.NSArray<java.lang.String> emailPatterns)

Constructs an Or qualifier for filtering an array of strings that might have the * wildcard character. Will be nice when we have regex in Java 1.4.

Parameters:

emailPatterns - array of email patterns

Returns:

or qualifier to match any of the given patterns

filterEmailAddresses

public com.webobjects.foundation.NSArray<java.lang.String> filterEmailAddresses(com.webobjects.foundation.NSArray<java.lang.String> emailAddresses)

Filters an array of email addresses by the black and white lists.

Parameters:

emailAddresses - array of email addresses to be filtered

Returns:

array of filtered email addresses