atg.service.email.examiner
Interface EmailExaminer

All Known Implementing Classes:

atg.service.email.examiner.EmailExaminerImpl, EximEmailExaminer, RegExEmailExaminer, SendmailEmailExaminer

public interface EmailExaminer

This interface provides methods for examining javax.mail.Message objects. It's designed to get information about bounced emails in particular via information found in the body or headers of the email. Each particular MTA provides information about the nature of the bounced email in their own format, and thus it is expected that an implementation of an EmailExaminer should be created for each specific MTA that the user is expecting to receive bounced emails from.

Field Summary

static java.lang.String

CLASS_VERSION Class version string

Method Summary

java.lang.Object	examineEmail(javax.mail.Message pMessage) This is a generic method that can be used to examine a message in an implementation-specific manner and in a context that is meaningful to the developer implementing it.
java.lang.String	getBouncedEmailAddress(javax.mail.Message pMessage) Gets the email address of the bounced recipient from the given javax.mail.Message.
java.lang.String	getBouncedEnhancedStatusCode(javax.mail.Message pMessage) Gets the enhanced status code from the given bounced email.
java.lang.String	getBouncedErrorMessage(javax.mail.Message pMessage) Gets the error message from the given bounced email.
java.lang.String	getBouncedReplyCode(javax.mail.Message pMessage) Gets the reply code (RFC 821) of the given bounced message.
java.lang.String[]	getMonitoredBounceReplyCodes() Gets the reply codes that indicate an email is bounced
java.lang.String	getMTAName() Gets the name of the MTA that this examiner is valid for For example, if this returns the value "sendmail", then the user can assume that this examiner will correctly get information from bounced emails in a sendmail-based format
boolean	isBouncedEmail(javax.mail.Message pMessage) Checks the passed in javax.mail.Message object for indications that it has been bounced.
void	setMonitoredBounceReplyCodes(java.lang.String[] pReplyCodes) Sets the reply codes that indicate an email is bounced This can be any number of standard SMTP codes defined in RFC 821.

Field Detail

CLASS_VERSION

static final java.lang.String CLASS_VERSION

Class version string

See Also:

Constant Field Values

Method Detail

getMTAName

java.lang.String getMTAName()

Gets the name of the MTA that this examiner is valid for For example, if this returns the value "sendmail", then the user can assume that this examiner will correctly get information from bounced emails in a sendmail-based format

Returns:

the name of the MTA format that bounced emails will be checked against

setMonitoredBounceReplyCodes

void setMonitoredBounceReplyCodes(java.lang.String[] pReplyCodes)

Sets the reply codes that indicate an email is bounced This can be any number of standard SMTP codes defined in RFC 821. Each examiner will have its own method of knowing where to look for this code, based on some other string indicator, e.g. sendmail will look for "<<< " before a reply code

Parameters:

pReplyCodes - an array of RFC 821 reply codes that, if present, will indicate a message has been bounced

getMonitoredBounceReplyCodes

java.lang.String[] getMonitoredBounceReplyCodes()

Gets the reply codes that indicate an email is bounced

Returns:

the reply codes that indicate an email is bounced

isBouncedEmail

boolean isBouncedEmail(javax.mail.Message pMessage)
                       throws javax.mail.MessagingException,
                              EmailException

Checks the passed in javax.mail.Message object for indications that it has been bounced. Each MTA sends a formatted reply for bounced emails, so this implementation will depend on the specific MTA examiner used.

Parameters:

pMessage - the message to examine

Returns:

true if the message has been bounced, false otherwise

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified NOTE: An exception should NOT be thrown if the given message is not in a format recognized by this examiner. In most cases, a list of examiners will be called upon to see if any consider the message as bounced in a given operation. Developers are expected to return false in this case.

getBouncedEmailAddress

java.lang.String getBouncedEmailAddress(javax.mail.Message pMessage)
                                        throws javax.mail.MessagingException,
                                               EmailException

Gets the email address of the bounced recipient from the given javax.mail.Message. This address can be found via MTA-specific headers, or body content and is implementation dependent. If the passed in message has not been found to be bounced, this should return null.

Parameters:

pMessage - the bounced message to examine

Returns:

the bounced email address of the intended recipient, or null if cannot be determined from the given pMessage i.e. the formatting is not what was expected, or the message has not been determined as bounced

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified NOTE: An exception should NOT be thrown if the given message is not in a format recognized by this examiner. In most cases, a list of examiners will be called upon to see if any consider the message as bounced in a given operation. Developers are expected to return null in this case.

getBouncedErrorMessage

java.lang.String getBouncedErrorMessage(javax.mail.Message pMessage)
                                        throws javax.mail.MessagingException,
                                               EmailException

Gets the error message from the given bounced email. The location of this message is MTA-specific, and it's the developer's responsibility to accurately determine its location in a given message. The passed in pMessage should also be declared as bounced before looking for the error message, otherwise null should be returned

Parameters:

pMessage - the bounced message to examine

Returns:

the error message of the bounced email, indicating why it was bounced, or null if the message cannot be determined from the give pMessage i.e. the formatting is not what was expected, or the message has not been determined as bounced

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified NOTE: An exception should NOT be thrown if the given message is not in a format recognized by this examiner. In most cases, a list of examiners will be called upon to see if any consider the message as bounced in a given operation. Developers are expected to return null in this case.

getBouncedEnhancedStatusCode

java.lang.String getBouncedEnhancedStatusCode(javax.mail.Message pMessage)
                                              throws javax.mail.MessagingException,
                                                     EmailException

Gets the enhanced status code from the given bounced email. Enchanced status codes are defined in RFC 1893. The location of this code is MTA-specific, and it's the developer's responsibility to accurately determine its location in a given message. The passed in pMessage should also be declared as bounced before looking for the status code, otherwise null should be returned.

Parameters:

pMessage - the bounced message to examine

Returns:

the enhanced status code of the bounced email, indicating why it was bounced, or null if the message cannot be determined from the give pMessage i.e. the formatting is not what was expected, or the message has not been determined as bounced

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified NOTE: An exception should NOT be thrown if the given message is not in a format recognized by this examiner. In most cases, a list of examiners will be called upon to see if any consider the message as bounced in a given operation. Developers are expected to return null in this case.

getBouncedReplyCode

java.lang.String getBouncedReplyCode(javax.mail.Message pMessage)
                                     throws javax.mail.MessagingException,
                                            EmailException

Gets the reply code (RFC 821) of the given bounced message. This reply code should exist in the getMonitoredReplyCodes array. The location of this code is MTA-specific and is the developers responsibility to determine its location in a given message. The passed in pMessage should also be declared as bounced before looking for the reply code, otherwise null should be returned

Parameters:

pMessage - the bounced message to examine

Returns:

the reply code of the bounced email, indicating why it was bounced, or null if the message cannot be determined from the give pMessage i.e. the formatting is not what was expected, or the message has not been determined as bounced

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified NOTE: An exception should NOT be thrown if the given message is not in a format recognized by this examiner. In most cases, a list of examiners will be called upon to see if any consider the message as bounced in a given operation. Developers are expected to return null in this case.

examineEmail

java.lang.Object examineEmail(javax.mail.Message pMessage)
                              throws javax.mail.MessagingException,
                                     EmailException

This is a generic method that can be used to examine a message in an implementation-specific manner and in a context that is meaningful to the developer implementing it. If the rest of this interface's methods don't supply a developer with the information they require, this method can be used to perform the work. The return value can be anything the implementor deems meaningful. This method does NOT need to be fully implemented, and can be a no-op

Parameters:

pMessage - the message to examine

Returns:

an object that has meaning to the implementor

Throws:

javax.mail.MessagingException - if a problem occurs while calling methods on the pMessage object

EmailException - if a problem occurs during the parsing of the content, of invalid arguments are specified