atg.service.email
Class EmailFormHandler

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.droplet.EmptyFormHandler
              atg.droplet.GenericFormHandler
                  atg.service.email.EmailFormHandler

All Implemented Interfaces:

DropletFormHandler, NameContextBindingListener, NameContextElement, NameResolver, AdminableService, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, atg.nucleus.logging.VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener

Direct Known Subclasses:

B2CEmailFormHandler

public class EmailFormHandler
extends GenericFormHandler

This class allows an application to send an email using data entered by the user in an html form. It refers to an SMTPEmailSender service to perform the send operation.

A typical form would look like this:

<form action="`request.getRequestURI()`" method="POST"> From: <input type="text" bean="EmailFormHandler.sender"> <br> To: <input type="text" bean="EmailFormHandler.recipient"> <br> Subject: <input type="text" bean="EmailFormHandler.subject"> <p> Body: <input type="textarea" bean="EmailFormHandler.body"><p> <input type="submit" bean="EmailFormHandler.sendEmail"> </form>

See Also:

SMTPEmailSender

Field Summary

static java.lang.String	CLASS_VERSION
protected static java.lang.String	MSG_EMPTY_MESSAGE
protected static java.lang.String	MSG_INVALID_RECIPIENT_EMAIL
protected static java.lang.String	MSG_INVALID_SENDER_EMAIL
protected static java.lang.String	MSG_NO_EMAIL_HOST_NAME
protected static java.lang.String	MSG_NO_RECIPIENT_EMAIL
protected static java.lang.String	MSG_NO_SENDER_EMAIL
static java.lang.String	RESOURCE_BUNDLE Resource bundle that holds messages to dispay to the end user

Fields inherited from class atg.droplet.GenericFormHandler

PARAM_DEFER_FORWARD_OR_REDIRECT, PARAM_USE_FORWARDS

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

EmailFormHandler()
Constructs an EmailFormHandler object.

Method Summary

java.lang.String	getBody() Returns property body.
java.util.Locale	getDefaultLocale() Returns property DefaultLocale.
SMTPEmailSender	getEmailSenderService() Returns property emailSenderService.
java.lang.String	getRecipient() Returns property recipient.
java.lang.String	getSender() Returns property sender.
java.lang.String	getSendErrorURL() Returns property sendErrorURL
java.lang.String	getSendSuccessURL() Returns property sendSuccessURL.
java.lang.String	getSubject() Returns property subject.
java.util.Locale	getUserLocale(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Returns the locale associated with the request.
boolean	handleSendEmail(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) This method is typically associated with the form's submit button.
boolean	isUseRequestLocale() Returns property UseRequestLocale
protected boolean	sendMail(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Perform the actual send operation.
void	setBody(java.lang.String pBody) Sets property body, the content of the email.
void	setDefaultLocale(java.util.Locale pDefaultLocale) Sets property DefaultLocale for localizing user messages
void	setEmailSenderService(SMTPEmailSender pEmailSender) Sets property emailSenderService, wich will be used to send the email.
void	setRecipient(java.lang.String pRecipient) Sets property recipient, used as the To: tag of the email.
void	setSender(java.lang.String pSender) Sets property sender, used as the From: tag of the email.
void	setSendErrorURL(java.lang.String pSendErrorURL) Sets property sendErrorURL, identifying the page this method will redirect to if there is an error sending the email.
void	setSendSuccessURL(java.lang.String pSendSuccessURL) Sets property sendSuccessURL, identifying the page this method will redirect to if the email is successfully sent.
void	setSubject(java.lang.String pSubject) Sets property subject, used as the Subject: tag of the email.
void	setUseRequestLocale(boolean pUseRequestLocale) Sets property UseRequestLocale which determines whether to use the requestLocale for localizing user messages
java.lang.String	toString()
protected boolean	validate(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Validate the email's fields for correctness.

Methods inherited from class atg.droplet.GenericFormHandler

addFormException, addUncheckedFormException, afterSet, beforeSet, checkFormRedirect, createFormSubmissionMessage, getCancelURL, getCheckForValidSession, getFormError, getFormExceptions, getFormName, getMessagePort, getMessageSource, getMessageType, getPropertyExceptions, getSendMessages, getUncheckedFormExceptions, handleCancel, handleFormException, handleUncheckedFormException, hasUncheckedFormExceptions, isDeferForwardsAndRedirects, isRestorableForm, isUseForwards, isValidSession, redirectOrForward, resetFormExceptions, setCancelURL, setCheckForValidSession, setDeferForwardsAndRedirects, setFormName, setMessagePort, setMessageSource, setMessageType, setRestorableForm, setSendMessages, setUseForwards

Methods inherited from class atg.droplet.EmptyFormHandler

afterGet, beforeGet

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static final java.lang.String CLASS_VERSION

See Also:

Constant Field Values

RESOURCE_BUNDLE

public static java.lang.String RESOURCE_BUNDLE

Resource bundle that holds messages to dispay to the end user

MSG_NO_SENDER_EMAIL

protected static final java.lang.String MSG_NO_SENDER_EMAIL

See Also:

Constant Field Values

MSG_INVALID_SENDER_EMAIL

protected static final java.lang.String MSG_INVALID_SENDER_EMAIL

See Also:

Constant Field Values

MSG_NO_RECIPIENT_EMAIL

protected static final java.lang.String MSG_NO_RECIPIENT_EMAIL

See Also:

Constant Field Values

MSG_INVALID_RECIPIENT_EMAIL

protected static final java.lang.String MSG_INVALID_RECIPIENT_EMAIL

See Also:

Constant Field Values

MSG_EMPTY_MESSAGE

protected static final java.lang.String MSG_EMPTY_MESSAGE

See Also:

Constant Field Values

MSG_NO_EMAIL_HOST_NAME

protected static final java.lang.String MSG_NO_EMAIL_HOST_NAME

See Also:

Constant Field Values

Constructor Detail

EmailFormHandler

public EmailFormHandler()

Constructs an EmailFormHandler object.

Method Detail

setEmailSenderService

public void setEmailSenderService(SMTPEmailSender pEmailSender)

Sets property emailSenderService, wich will be used to send the email. Note that it will be possible to send email only if the hostname and port number properties of that component are properly configured.

getEmailSenderService

public SMTPEmailSender getEmailSenderService()

Returns property emailSenderService.

setSendSuccessURL

public void setSendSuccessURL(java.lang.String pSendSuccessURL)

Sets property sendSuccessURL, identifying the page this method will redirect to if the email is successfully sent. If null, no redirection is performed.

getSendSuccessURL

public java.lang.String getSendSuccessURL()

Returns property sendSuccessURL.

setSendErrorURL

public void setSendErrorURL(java.lang.String pSendErrorURL)

Sets property sendErrorURL, identifying the page this method will redirect to if there is an error sending the email. If null, no redirection is performed.

getSendErrorURL

public java.lang.String getSendErrorURL()

Returns property sendErrorURL

setSender

public void setSender(java.lang.String pSender)

Sets property sender, used as the From: tag of the email. This field should contain a valid email address, either in the form email-address@hostname, or in the form user name <email-address@hostname>.

getSender

public java.lang.String getSender()

Returns property sender.

setRecipient

public void setRecipient(java.lang.String pRecipient)

Sets property recipient, used as the To: tag of the email. This field should contain a valid email address, either in the form email-address@hostname, or in the form user name <email-address@hostname>.

getRecipient

public java.lang.String getRecipient()

Returns property recipient.

setSubject

public void setSubject(java.lang.String pSubject)

Sets property subject, used as the Subject: tag of the email.

getSubject

public java.lang.String getSubject()

Returns property subject.

setBody

public void setBody(java.lang.String pBody)

Sets property body, the content of the email.

getBody

public java.lang.String getBody()

Returns property body.

setDefaultLocale

public void setDefaultLocale(java.util.Locale pDefaultLocale)

Sets property DefaultLocale for localizing user messages

getDefaultLocale

public java.util.Locale getDefaultLocale()

Returns property DefaultLocale. If the property value is null, then JVM's default locale is returned.

setUseRequestLocale

public void setUseRequestLocale(boolean pUseRequestLocale)

Sets property UseRequestLocale which determines whether to use the requestLocale for localizing user messages

isUseRequestLocale

public boolean isUseRequestLocale()

Returns property UseRequestLocale

sendMail

protected boolean sendMail(DynamoHttpServletRequest pRequest,
                           DynamoHttpServletResponse pResponse)
                    throws javax.servlet.ServletException,
                           java.io.IOException

Perform the actual send operation. A derived class will typically override this method, and either send the email itself, or call this method after performing some editing on the message.

Returns:

a boolean value indicating whether the send operation was successful

Throws:

javax.servlet.ServletException

java.io.IOException

validate

protected boolean validate(DynamoHttpServletRequest pRequest,
                           DynamoHttpServletResponse pResponse)
                    throws javax.servlet.ServletException,
                           java.io.IOException

Validate the email's fields for correctness.

Currently only checks that the sender and recipient addresses contain a '@' and that both the subject andd body aren't empty.
This protected method is intended to be overriden by a subclass to provide customized error checking.

Returns:

a boolean value indicating whether the email message is ok.

Throws:

javax.servlet.ServletException

java.io.IOException

handleSendEmail

public boolean handleSendEmail(DynamoHttpServletRequest pRequest,
                               DynamoHttpServletResponse pResponse)
                        throws javax.servlet.ServletException,
                               java.io.IOException

This method is typically associated with the form's submit button. If the email is successfully sent, it redirects the user to the url identified by the sendSuccessURL property, if this property is set. If the email is not sent, it redirects the user to the url identified by the sendErrorURL property, if this property is set.

The sending operation is broken down into three steps:

1. The email's tags are validated by the validate() method
2. The email is sent by the sendMail() method
3. The user is redirected on success/failure by the handleSendEmail() handler

The sendMail() and validate() methods are protected methods that developers are encouraged to override in a derived class to perform customized error checking or to modify the email tags prior to sending the email.

Parameters:

pRequest - the request to be processed

pResponse - the response object for this request

Returns:

a boolean value, indicating that a redirect was not performed

Throws:

java.io.IOException

javax.servlet.ServletException

getUserLocale

public java.util.Locale getUserLocale(DynamoHttpServletRequest pRequest,
                                      DynamoHttpServletResponse pResponse)
                               throws javax.servlet.ServletException,
                                      java.io.IOException

Returns the locale associated with the request. The method first searches for a request paramater named locale. This value can be either a java.util.Locale object or a String which represents the locale. Next if the useRequestLocale property is true, then the locale of the request will be returned. Finally, if the locale cannot be determined, the the defaultLocale property is used.

Throws:

javax.servlet.ServletException

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this object