atg.droplet
Class GenericFormHandler

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

All Implemented Interfaces:

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

Direct Known Subclasses:

AbandonedOrderFormHandler, AdminFormHandler, ApprovalFormHandler, BaseSearchFormHandler, CancelOrder, CompareSkusFormHandler, CouponFormHandler, DateEditor, DBCopyFormHandler, EmailFormHandler, FilterFormHandler, InventoryFormHandler, MultipleSubmitHelper, OrderModifierFormHandler, OrderStatusFormHandler, ProductListHandler, ProfileForm, PurchaseProcessFormHandler, RepositoryFormHandler, SearchFormHandler, SearchFormHandler, ShippingGroupUpdateFormHandler, SimpleSQLFormHandler, SQLTableManager, SwitchDataSourceFormHandler, TransactionalFormHandler

public class GenericFormHandler
extends EmptyFormHandler

This form handler performs basic error checking operations. It typically is sub-classed by form handlers that do more stuff.

Field Summary

static java.lang.String	CLASS_VERSION
static java.lang.String	PARAM_DEFER_FORWARD_OR_REDIRECT The name of a parameter that represents whether to defer the execution of forwards and redirects until after all form handling has been completed.
static java.lang.String	PARAM_USE_FORWARDS The name of a parameter that represents whether to 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

GenericFormHandler()

Method Summary

void	addFormException(DropletException exc) Adds a new exception to the list of FormExceptions.
void	addUncheckedFormException(java.lang.Throwable exc) Adds a new exception to the list of FormExceptions.
boolean	afterSet(DynamoHttpServletRequest request, DynamoHttpServletResponse response) Clear out the current request we are processing.
boolean	beforeSet(DynamoHttpServletRequest request, DynamoHttpServletResponse response) Called before any setX methods on this form are set when a form that modifies properties of this form handler is submitted.
boolean	checkFormRedirect(java.lang.String pSuccessURL, java.lang.String pFailureURL, DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) If NO form errors are found, redirect to the SuccessURL.
java.io.Serializable	createFormSubmissionMessage(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
java.lang.String	getCancelURL()
boolean	getCheckForValidSession()
boolean	getFormError() Returns true if an error occurred while processing the form.
java.util.Vector	getFormExceptions() Returns the array of exceptions that occurred for display in the page
java.lang.String	getFormName()
java.lang.String	getMessagePort()
atg.nucleus.dms.DASMessageSource	getMessageSource()
java.lang.String	getMessageType()
java.util.Dictionary	getPropertyExceptions() Returns the propertyExceptions property.
boolean	getSendMessages()
java.util.List	getUncheckedFormExceptions() Returns the array of unchecked exceptions that occurred for display in the page
boolean	handleCancel(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) This method redirects to the value of the cancelURL property, if that property is set to a non-null value.
void	handleFormException(DropletFormException exception, DynamoHttpServletRequest request, DynamoHttpServletResponse response) Called when an exception occurs while processing form submissions
void	handleUncheckedFormException(java.lang.Throwable exception, DynamoHttpServletRequest request, DynamoHttpServletResponse response) Called when an unchecked exception occurs while processing form submissions
boolean	hasUncheckedFormExceptions() Returns true if an error occurred while processing the form.
boolean	isDeferForwardsAndRedirects() Get whether to defer forwards and redirects until after form handling has completed, or to execute forwards and redirects imediately.
boolean	isRestorableForm()
boolean	isUseForwards() Get whether to use forwards rather then redirects
boolean	isValidSession(DynamoHttpServletRequest pRequest) Returns true if this is a valid session for processing the form.
protected void	redirectOrForward(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse, java.lang.String pURL) Forward or redirect, as required.
void	resetFormExceptions() Clears out all form exceptions
void	setCancelURL(java.lang.String pCancelURL) Sets the property CancelURL.
void	setCheckForValidSession(boolean pCheckForValidSession) Sets the property CheckForValidSession.
void	setDeferForwardsAndRedirects(boolean pDeferForwardsAndRedirects) Set whether to defer forwards and redirects until after form handling has completed, or to execute forwards and redirects imediately.
void	setFormName(java.lang.String pFormName) Sets the property formName.
void	setMessagePort(java.lang.String pMessagePort) Sets the property messagePort.
void	setMessageSource(atg.nucleus.dms.DASMessageSource pMessageSource) Sets the property messageSource.
void	setMessageType(java.lang.String pMessageType) Sets the property messageType.
void	setRestorableForm(boolean pRestorableForm) Sets the property RestorableForm.
void	setSendMessages(boolean pSendMessages) Sets the property sendMessages to indicate if messages are to be sent.
void	setUseForwards(boolean pUseForwards) Set whether to use forwards rather then redirects.

Methods inherited from class atg.droplet.EmptyFormHandler

afterGet, beforeGet

Methods inherited from class atg.nucleus.GenericService

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

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, 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, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

PARAM_USE_FORWARDS

public static final java.lang.String PARAM_USE_FORWARDS

The name of a parameter that represents whether to use forwards. The form handler defaults to using redirects. Set this to "true" to use forwards instead.

See Also:

Constant Field Values

PARAM_DEFER_FORWARD_OR_REDIRECT

public static final java.lang.String PARAM_DEFER_FORWARD_OR_REDIRECT

The name of a parameter that represents whether to defer the execution of forwards and redirects until after all form handling has been completed.

Deferred forwards and redirects allow form handlers (often those that manage their own transactions) to forward/redirect after the afterSet method has been called (once the transaction has completed). A common design pattern is to create and end a transaction in before and after set, respectively. If a form handler requests a forward inside that transaction, then we don't necessarily want to render the forward request in the same transaction. This is especially true if the form handler has rolled back the transaction. Also, deferring the forward until after the transaction completes insulates the work the form handler performed from a rollback set by the forwarded page. Likewise, when a form handler redirects, it is often valuable to defer executing a redirect until after the transaction completes to prevent the subsequent request from being processed before a transaction completes.

Set this parameter to "true" to defer forwards/redirects until after the afterSet method has been called.

See Also:

Constant Field Values

Constructor Detail

GenericFormHandler

public GenericFormHandler()

Method Detail

beforeSet

public boolean beforeSet(DynamoHttpServletRequest request,
                         DynamoHttpServletResponse response)
                  throws DropletFormException

Called before any setX methods on this form are set when a form that modifies properties of this form handler is submitted.

Specified by:

beforeSet in interface DropletFormHandler

Overrides:

beforeSet in class EmptyFormHandler

Returns:

true if form processing should continue, false if it should be aborted

Throws:

DropletFormException

afterSet

public boolean afterSet(DynamoHttpServletRequest request,
                        DynamoHttpServletResponse response)
                 throws DropletFormException

Clear out the current request we are processing.

Specified by:

afterSet in interface DropletFormHandler

Overrides:

afterSet in class EmptyFormHandler

Returns:

true if request processing should continue and the requested URL should be served, false if it should be aborted. If false is returned, you typically have already completed the request with a redirect or by sending output to the output stream.

Throws:

DropletFormException

handleFormException

public void handleFormException(DropletFormException exception,
                                DynamoHttpServletRequest request,
                                DynamoHttpServletResponse response)

Called when an exception occurs while processing form submissions

Specified by:

handleFormException in interface DropletFormHandler

Overrides:

handleFormException in class EmptyFormHandler

handleUncheckedFormException

public void handleUncheckedFormException(java.lang.Throwable exception,
                                         DynamoHttpServletRequest request,
                                         DynamoHttpServletResponse response)

Called when an unchecked exception occurs while processing form submissions

Specified by:

handleUncheckedFormException in interface DropletFormHandler

Overrides:

handleUncheckedFormException in class EmptyFormHandler

setSendMessages

public void setSendMessages(boolean pSendMessages)

Sets the property sendMessages to indicate if messages are to be sent.

getSendMessages

public boolean getSendMessages()

Returns:

The value of the property sendMessages.

setMessageSource

public void setMessageSource(atg.nucleus.dms.DASMessageSource pMessageSource)

Sets the property messageSource. The DASMessageSource component which will handle sending the message.

getMessageSource

public atg.nucleus.dms.DASMessageSource getMessageSource()

Returns:

The value of the property messageSource.

setFormName

public void setFormName(java.lang.String pFormName)

Sets the property formName. Set to the name of the form from which the submit was issued.

getFormName

public java.lang.String getFormName()

Returns:

The value of the property formName - default to nucleus component name

setMessageType

public void setMessageType(java.lang.String pMessageType)

Sets the property messageType. The type of the JMS message to be sent. Default is the type specified in the Patch Bay definition file for form submission events. (ie atg.das.FormSubmission)

getMessageType

public java.lang.String getMessageType()

Returns:

The value of the property messageType.

setMessagePort

public void setMessagePort(java.lang.String pMessagePort)

Sets the property messagePort. JMS port on which the message is sent. Default is the port specified in the Patch Bay definition file for form submission events.

getMessagePort

public java.lang.String getMessagePort()

Returns:

The value of the property messagePort.

setUseForwards

public void setUseForwards(boolean pUseForwards)

Set whether to use forwards rather then redirects.

isUseForwards

public boolean isUseForwards()

Get whether to use forwards rather then redirects

setDeferForwardsAndRedirects

public void setDeferForwardsAndRedirects(boolean pDeferForwardsAndRedirects)

Set whether to defer forwards and redirects until after form handling has completed, or to execute forwards and redirects imediately.

Deferred forwards and redirects allow form handlers (often those that manage their own transactions) to forward/redirect after the afterSet method has been called (once the transaction has completed). A common design pattern is to create and end a transaction in before and after set, respectively. If a form handler requests a forward inside that transaction, then we don't necessarily want to render the forward request in the same transaction. This is especially true if the form handler has rolled back the transaction. Also, deferring the forward until after the transaction completes insulates the work the form handler performed from a rollback set by the forwarded page. Likewise, when a form handler redirects, it is often valuable to defer executing a redirect until after the transaction completes to prevent the subsequent request from being processed before a transaction completes.

Set this property to "true" to defer forwards and redirects until after the form handling has completed.

isDeferForwardsAndRedirects

public boolean isDeferForwardsAndRedirects()

Get whether to defer forwards and redirects until after form handling has completed, or to execute forwards and redirects imediately.

Deferred forwards and redirects allow form handlers (often those that manage their own transactions) to forward/redirect after the afterSet method has been called (once the transaction has completed). A common design pattern is to create and end a transaction in before and after set, respectively. If a form handler requests a forward inside that transaction, then we don't necessarily want to render the forward request in the same transaction. This is especially true if the form handler has rolled back the transaction. Also, deferring the forward until after the transaction completes insulates the work the form handler performed from a rollback set by the forwarded page. Likewise, when a form handler redirects, it is often valuable to defer executing a redirect until after the transaction completes to prevent the subsequent request from being processed before a transaction completes.

If this property is set to "true", forwards and redirects will be deferred until after the form handling has completed.

createFormSubmissionMessage

public java.io.Serializable createFormSubmissionMessage(DynamoHttpServletRequest pRequest,
                                                        DynamoHttpServletResponse pResponse)

getFormError

public boolean getFormError()

Returns true if an error occurred while processing the form.

getFormExceptions

public java.util.Vector getFormExceptions()

Returns the array of exceptions that occurred for display in the page

hasUncheckedFormExceptions

public boolean hasUncheckedFormExceptions()

Returns true if an error occurred while processing the form.

getUncheckedFormExceptions

public java.util.List getUncheckedFormExceptions()

Returns the array of unchecked exceptions that occurred for display in the page

setRestorableForm

public void setRestorableForm(boolean pRestorableForm)

Sets the property RestorableForm. Set this property to true if this form handler can properly process form results on a session which has been restored using the session backup server. This property is only used by the isValidSession method. That method gets used to automatically detect an error and redirect to the error page when your session has expired since the form was rendered.

You should set this property to true, if you are using the checkFormRedirect method in your handleX method, and all of the data needed to process this form in your session is restored by the session backup process.

Note that if your form does not rely on any data in the session at all for processing, you do not need to worry about setting this property. Instead, make sure to set the checkForValidSession property to false.

Parameters:

pRestorableForm - new value to set

isRestorableForm

public boolean isRestorableForm()

Returns:

The value of the property RestorableForm.

setCheckForValidSession

public void setCheckForValidSession(boolean pCheckForValidSession)

Sets the property CheckForValidSession. If your form handler depends on session information to be maintained between when the form was rendered and when the form is submitted, you can set this property to true to have this form handler automatically detect when a form submit occurs on a new session. This error checking only works if you use the checkFormRedirect method in your handleX method.

If you set this property to true and use the checkFormRedirect method, it will add a form exception with the code "sessionExpired" and redirect to the supplied errorURL if the session expired between when the form was rendered and submitted.

Note that if the session backup feature is enabled, you should be sure to set the RestorableForm property to true if your form can work properly on a restored session.

Parameters:

pCheckForValidSession - new value to set

getCheckForValidSession

public boolean getCheckForValidSession()

Returns:

The value of the property CheckForValidSession.

isValidSession

public boolean isValidSession(DynamoHttpServletRequest pRequest)

Returns true if this is a valid session for processing the form. This is meant to be called during the form processing stage of the request handling pipeline (i.e. from a set or handle method in the form).

addFormException

public void addFormException(DropletException exc)

Adds a new exception to the list of FormExceptions.

addUncheckedFormException

public void addUncheckedFormException(java.lang.Throwable exc)

Adds a new exception to the list of FormExceptions.

resetFormExceptions

public void resetFormExceptions()

Clears out all form exceptions

getPropertyExceptions

public java.util.Dictionary getPropertyExceptions()

Returns the propertyExceptions property. This is a Dictionary that returns the current form exceptions keyed off of the name of the property that generated that exception. A DynamicPropertyMapper is registered for these exceptions so that you can access them as properties in a jhtml page. If there was no exception for a particular property, a null value is returned for that property.

setCancelURL

public void setCancelURL(java.lang.String pCancelURL)

Sets the property CancelURL. If this value is set to non-null, we redirect to this URL when the handleCancel method is called.

getCancelURL

public java.lang.String getCancelURL()

Returns:

The value of the property CancelURL.

handleCancel

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

This method redirects to the value of the cancelURL property, if that property is set to a non-null value. You should override this if you want to clear the form values when the form is cancelled for a session scoped form handler.

Throws:

javax.servlet.ServletException

java.io.IOException

checkFormRedirect

public boolean checkFormRedirect(java.lang.String pSuccessURL,
                                 java.lang.String pFailureURL,
                                 DynamoHttpServletRequest pRequest,
                                 DynamoHttpServletResponse pResponse)
                          throws javax.servlet.ServletException,
                                 java.io.IOException

If NO form errors are found, redirect to the SuccessURL. If form errors are found, redirect to the FailureURL.

Parameters:

pNoErrorsURL - The URL to redirect to if there were no form errors. If a null value is passed in, no redirect occurs.

pErrorsURL - The URL to redirect to if form errors were found. If a null value is passed in, no redirect occurs.

pRequest - the servlet's request

pResponse - the servlet's response

Returns:

If redirect (for whatever reason) to a new page occurred, return false. If NO redirect occurred, return true.

Throws:

javax.servlet.ServletException - if there was an error while executing the code

java.io.IOException - if there was an error with servlet io

redirectOrForward

protected void redirectOrForward(DynamoHttpServletRequest pRequest,
                                 DynamoHttpServletResponse pResponse,
                                 java.lang.String pURL)
                          throws java.io.IOException,
                                 javax.servlet.ServletException

Forward or redirect, as required.

Parameters:

pRequest - the servlet's request

pResponse - the servlet's response

pURL - the url to redirect or forward to.

Throws:

java.io.IOException

javax.servlet.ServletException