com.isti.quakewatch.util
Class JavaMailUtil

java.lang.Object
  extended by com.isti.util.ErrorMessageMgr
      extended by com.isti.quakewatch.util.JavaMailUtil
All Implemented Interfaces:
ErrorMsgMgrIntf

public class JavaMailUtil
extends ErrorMessageMgr

Class JavaMailUtil defines configuration and utility methods for using Sun's JavaMail package to send mail via an SMTP server. If an all-in-one program jar is being built then the following files need to be included: "META-INF/javamail.providers" & "META-INF/javamail.address.map" from "smtp.jar", and "META-INF/javamail.charset.map" & "META-INF/javamail.mailcap" from "mailapi.jar".


Field Summary
 CfgProperties configPropsObj
          Configuration-properties object; may be passed in.
 CfgPropItem dontSendPartialFlagProp
          Flag set true for no-send if some recipient addresses are bad.
 CfgPropItem initSMTPTimeoutSecProp
          Timeout for initial connection to SMTP server, in seconds.
 CfgProperties localPropsObj
          Config-properties object containing only mail items.
 CfgPropItem mailDebugFlagProp
          Flag for JavaMail session debug messages, true = debug on.
 CfgPropItem sendSMTPTimeoutSecProp
          Timeout for send-connections to SMTP server, in seconds.
protected  boolean sessionPropsChangedFlag
          Flag set true to indicate session config-properties change.
protected  Session smtpMailSessionObj
          Session object for sending SMTP mail.
 CfgPropItem smtpServerAddressProp
          Address of SMTP server for sending mail ("URL[:port]").
 CfgPropItem smtpServerAuthProp
          SMTP server authentication ("username,password[,STARTTLS]").
protected  java.lang.String xMailerHeaderString
          String for "X-Mailer" header in messages.
 
Constructor Summary
JavaMailUtil()
          Constructs a mail utilities object.
JavaMailUtil(CfgProperties propsObj, CfgPropItem smtpServerAddressProp, java.lang.Object groupSelObj)
          Constructs a mail utilities object.
 
Method Summary
protected  Session createMailSession(boolean initialFlag)
          Creates an email session object.
 CfgProperties getConfigProps()
          Returns the 'CfgProperties' object holding the configuration-property items.
static java.lang.Exception getLastMessagingException(java.lang.Throwable throwableObj)
          Returns the last nested exception for the given 'MessagingException'.
 CfgProperties getLocalProps()
          Returns the 'CfgProperties' object holding the local configuration-property items (related to mail settings).
 java.lang.String getXMailerHeaderString()
          Returns the string for the "X-Mailer" header in messages.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr)
          Sends an email message using the given parameters.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr, java.util.Date sentDateObj)
          Sends an email message using the given parameters.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr, java.util.Date sentDateObj, boolean xMailerHdrFlag)
          Sends an email message using the given parameters.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String fromNameStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr)
          Sends an email message using the given parameters.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String fromNameStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr, java.util.Date sentDateObj)
          Sends an email message using the given parameters.
 boolean sendEmailMessage(java.lang.String fromAddrStr, java.lang.String fromNameStr, java.lang.String recipientsStr, java.lang.String subjectStr, java.lang.String bodyTextStr, java.util.Date sentDateObj, boolean xMailerHdrFlag)
          Sends an email message using the given parameters.
 void setXMailerHeaderString(java.lang.String str)
          Sets the string for the "X-Mailer" header in messages.
 boolean testServerConnection()
          Tests the connection to the SMTP mail server.
 boolean validateFromAddress(java.lang.String fromAddrStr)
          Checks the validity of the given "from" email address.
 boolean validateFromAddress(java.lang.String fromAddrStr, java.lang.String fromNameStr)
          Checks the validity of the given "from" email address.
 
Methods inherited from class com.isti.util.ErrorMessageMgr
clearErrorMessageString, clearFetchedErrorMessage, enterErrorMessageString, getErrorMessageFlag, getErrorMessageString, getUnfetchedMessageFlag, setErrorMessageString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sessionPropsChangedFlag

protected boolean sessionPropsChangedFlag
Flag set true to indicate session config-properties change.


smtpMailSessionObj

protected Session smtpMailSessionObj
Session object for sending SMTP mail.


xMailerHeaderString

protected java.lang.String xMailerHeaderString
String for "X-Mailer" header in messages.


configPropsObj

public final CfgProperties configPropsObj
Configuration-properties object; may be passed in.


localPropsObj

public final CfgProperties localPropsObj
Config-properties object containing only mail items.


smtpServerAddressProp

public final CfgPropItem smtpServerAddressProp
Address of SMTP server for sending mail ("URL[:port]").


initSMTPTimeoutSecProp

public final CfgPropItem initSMTPTimeoutSecProp
Timeout for initial connection to SMTP server, in seconds.


sendSMTPTimeoutSecProp

public final CfgPropItem sendSMTPTimeoutSecProp
Timeout for send-connections to SMTP server, in seconds.


dontSendPartialFlagProp

public final CfgPropItem dontSendPartialFlagProp
Flag set true for no-send if some recipient addresses are bad.


mailDebugFlagProp

public final CfgPropItem mailDebugFlagProp
Flag for JavaMail session debug messages, true = debug on.


smtpServerAuthProp

public final CfgPropItem smtpServerAuthProp
SMTP server authentication ("username,password[,STARTTLS]"). Authentication options such as STARTTLS require a recent version of JavaMail.

Constructor Detail

JavaMailUtil

public JavaMailUtil(CfgProperties propsObj,
                    CfgPropItem smtpServerAddressProp,
                    java.lang.Object groupSelObj)
Constructs a mail utilities object.

Parameters:
propsObj - the configuration-properties object to add item to, or null to create a new configuration-properties object.
smtpServerAddressProp - the SMTP-server-address property object to use, or null to create one.
groupSelObj - the configuration-group-selection object to use, or null for none.

JavaMailUtil

public JavaMailUtil()
Constructs a mail utilities object.

Method Detail

setXMailerHeaderString

public void setXMailerHeaderString(java.lang.String str)
Sets the string for the "X-Mailer" header in messages.

Parameters:
str - the string to use, or null for none.

getXMailerHeaderString

public java.lang.String getXMailerHeaderString()
Returns the string for the "X-Mailer" header in messages.

Returns:
The "X-Mailer" header string to use, or null if none.

testServerConnection

public boolean testServerConnection()
Tests the connection to the SMTP mail server.

Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

validateFromAddress

public boolean validateFromAddress(java.lang.String fromAddrStr,
                                   java.lang.String fromNameStr)
Checks the validity of the given "from" email address.

Parameters:
fromAddrStr - the "from" address to use.
fromNameStr - the personal-name to associated with the "from" address, or null for none.
Returns:
true if the given email address is valid; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

validateFromAddress

public boolean validateFromAddress(java.lang.String fromAddrStr)
Checks the validity of the given "from" email address.

Parameters:
fromAddrStr - the "from" address to use.
Returns:
true if the given email address is valid; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String fromNameStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr,
                                java.util.Date sentDateObj,
                                boolean xMailerHdrFlag)
Sends an email message using the given parameters. This method blocks until the send attempt is completed, and thread-synchronizes using the mail-session object.

Parameters:
fromAddrStr - the "from" address to use.
fromNameStr - the personal-name to associated with the "from" address, or null for none.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
sentDateObj - the "sent" date to use, or null for no date in message.
xMailerHdrFlag - true to include the "X-Mailer" header text setup via the 'setXMailerHeaderString()' method; false for no "X-Mailer" header.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String fromNameStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr,
                                java.util.Date sentDateObj)
Sends an email message using the given parameters.

Parameters:
fromAddrStr - the "from" address to use.
fromNameStr - the personal-name to associated with the "from" address, or null for none.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
sentDateObj - the "sent" date to use, or null for no date in message.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String fromNameStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr)
Sends an email message using the given parameters. A "date" header showing the current date will be included in the message.

Parameters:
fromAddrStr - the "from" address to use.
fromNameStr - the personal-name to associated with the "from" address, or null for none.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr,
                                java.util.Date sentDateObj,
                                boolean xMailerHdrFlag)
Sends an email message using the given parameters.

Parameters:
fromAddrStr - the "from" address to use.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
sentDateObj - the "sent" date to use, or null for no date in message.
xMailerHdrFlag - true to include the "X-Mailer" header text setup via the 'setXMailerHeaderString()' method; false for no "X-Mailer" header.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr,
                                java.util.Date sentDateObj)
Sends an email message using the given parameters.

Parameters:
fromAddrStr - the "from" address to use.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
sentDateObj - the "sent" date to use, or null for no date in message.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

sendEmailMessage

public boolean sendEmailMessage(java.lang.String fromAddrStr,
                                java.lang.String recipientsStr,
                                java.lang.String subjectStr,
                                java.lang.String bodyTextStr)
Sends an email message using the given parameters. A "date" header showing the current date will be included in the message.

Parameters:
fromAddrStr - the "from" address to use.
recipientsStr - the list of recipient email addresses.
subjectStr - the subject text to use, or null for none.
bodyTextStr - the message-body text to use.
Returns:
true if successful; false if not (in which case an error message may be fetched via the 'getErrorMessageString()' method).

createMailSession

protected Session createMailSession(boolean initialFlag)
Creates an email session object.

Parameters:
initialFlag - true to use the "initial" SMTP-timeout configuration value; false to use the "sending" SMTP-timeout configuration value.
Returns:
A new 'Session' object, or null if an error occurred (in which case an error message may be fetched via the 'getErrorMessageString()' method).

getConfigProps

public CfgProperties getConfigProps()
Returns the 'CfgProperties' object holding the configuration-property items. If a 'CfgProperties' object parameter is passed in to the constructor then this method will return it.

Returns:
The 'CfgProperties' object holding the configuration-property items.

getLocalProps

public CfgProperties getLocalProps()
Returns the 'CfgProperties' object holding the local configuration-property items (related to mail settings).

Returns:
The 'CfgProperties' object holding the local configuration-property items (related to mail settings).

getLastMessagingException

public static java.lang.Exception getLastMessagingException(java.lang.Throwable throwableObj)
Returns the last nested exception for the given 'MessagingException'.

Parameters:
throwableObj - the 'MessagingException' object to use.
Returns:
The last nested exception, or null if none found.