atg.portal.framework

Class GearConfigFormHandler

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.droplet.EmptyFormHandler

atg.droplet.GenericFormHandler

atg.droplet.TransactionalFormHandler

atg.portal.admin.PortalGenericFormHandler

atg.portal.framework.GearConfigFormHandler

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, 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

public class GearConfigFormHandler
extends PortalGenericFormHandler

The GearConfigFormHandler is intended for use with instanceConfig, installConfig, initialConfig, and userConfig gear pages. Each gear should make its own Nucleus component for this form handler rather than sharing with another gear.

Single or multi page forms

The component may be request scoped for a simple form, or session scoped, for multi-page forms that should not be committed until the final submit. The submit method for multipage forms should be handleCollectValues() and the final page (or a single page form) should use handleConfirm().

How does this form handler work?

The way this form handler works is by collecting name-value pairs from the form data into its "values" property. In handleConfirm(), the formHandler iterates over the values map and sets gear parameters named by the keys in the values map to the values in the values map. At the end of handleConfirm the values dictionary is cleared.

Use this form handler to set all types of gear parameter values

There are several kinds of gear parameters:

• user parameter values (per gear per user)
• user parameter default values (per gear definition)
• gear parameter values (per gear instance)
• gear parameter default values (per gear definition)

To tell the form handler which type of parameter to set, use the properties paramType="instance" or "user" and setingDefaultValues="true" or "false".

Extending this form handler

It is likely that users will want to extend this form handler to perform specialized validation or extra processing of gear parameter values. To facilitate that, this class has the following no-op methods that can be overridden to do this processing:

• preCollectValues()
  Override this method to validate or process values between pages of a multipage form.
• postCollectValues()
  Override this method to do processing on values between pages of a multipage form. Errors registered here will be ignored.
• preConfirm()
  Override this method to validate or process values before setting the gear parameter values.
• postConfirm()
  Override this method to do processing on values after the gear parameter values have been set but before the transaction has been committed.

Error Handling

Use addFailureMessage() to stop processing (during preCollectValues(), preConfirm(), and postConfirm()) and cause a redirect to the failureURL. The method addSuccessMessage() will send a message to the user, but it will not halt processing and the redirect will go to successURL.

Pre-defaulting form field values

Because the fields of the gear configuration form correspond to "values" property this class rather than the actual gear parameters, the fields will not be properly defaulted as they are in many form handlers. Set the property "paramNames" to the space delimited list of parameter names you will be using in this form. The handleParamNames() method will pre-populate values from the gear parameters into the values property. Set this value after setting the values of properties "paramType" and "settingDefaultValues".

Properties:

successMessageProcessor

an instance of I18nMessageProcessor (/atg/portal/admin/SuccessMessageProcessor

failureMessageProcessor

an instance of I18nMessageProcessor (/atg/portal/admin/FailureMessageProcessor

paramType

instance or user. default = instance

settingDefaultValues

Set to true to set the default parameter user or instance parameter values on the GearDefinition. Set to false to set the per-user parameter values or per-gear instance instance paramter values. Default is false.

successURL

url to go to upon successful confirm

cancelURL

url to go to when user cancels out of form

failureURL

url to go to upon failure during handleConfirm. Note that this will be used extremely rarely. There are no user errors that can cause this error. Only programming errors and configuration errors will cause the need for this form handler's failureUrl, therefore, we recommend not using it.

values

The temporary holding area for form field values that will be set in the gearEnv in handleConfirm.

paramNames

The space delimited list of values to be used in this form. Setting this will cause the values to be pre-populated in the form.

For an example please see the reference gears.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string

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

Constructors

Constructor and Description
GearConfigFormHandler()

Method Summary

Methods

Modifier and Type	Method and Description
void	addFailureMessage(java.lang.String pResourceBundle, java.lang.String pMsgId, java.lang.String[] pArgs) Set a form processing error message that should be visible to the user.
void	addSuccessMessage(java.lang.String pResourceBundle, java.lang.String pMsgId, java.lang.String[] pArgs) Set a form processing info message that should be visible to the user.
void	beforeGet(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Calls super.beforeGet() and then enables the transactional form handler management features with setEnsureTransaction(true).
java.lang.String	getCancelUrl()
java.lang.String	getCommunityIdRequestParameter()
java.lang.String	getFailureUrl()
java.lang.String	getGearDefIdRequestParameter()
protected GearEnvironment	getGearEnvironment(DynamoHttpServletRequest pReq, DynamoHttpServletResponse pResp) sets up the gear environment.
java.lang.String	getGearIdRequestParameter()
java.lang.String	getParamNames() Returns a space delimited list of the names of the gear params that will be set in this form
java.lang.String	getParamType() choices are instance (default) or user
java.lang.String	getSuccessUrl()
java.util.Map	getValues()
boolean	handleCancel(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Cancel.
boolean	handleCollectValues(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) This method is intended for collecting the values from the form into the value map.
boolean	handleConfirm(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Take the values from the value property and set them into the gear environment user or instance parameters.
boolean	handleInitializeDefaultValues(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
boolean	handleParamNames(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) initialize the default values of the values map property by getting the parameter values out of the gear environment
boolean	isSettingDefaultValues() if true, then we are setting default values of the gear definition parameters
boolean	isSettingUserParams() convenience method to determine if we are setting user params or instance params
void	postCollectValues(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Override this method to do any post-processing.
void	postConfirm(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Override this method to do any post-processing.
void	preCollectValues(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Override this method to do any pre-processing or verification of form input.
void	preConfirm(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) Override this method to do any pre-processing or verification of form input.
void	setCancelUrl(java.lang.String s)
void	setCommunityIdRequestParameter(java.lang.String pCommunityIdRequestParameter)
void	setFailureUrl(java.lang.String s)
void	setGearDefIdRequestParameter(java.lang.String pGearDefIdRequestParameter)
void	setGearIdRequestParameter(java.lang.String pGearIdRequestParameter)
void	setInitializeDefaultValues(java.lang.String s)
void	setParamNames(java.lang.String pParamNames) Sets a space delimited list of the names of the gear params that will be set in this form
void	setParamType(java.lang.String pParamType) choices are instance (default) or user
void	setSettingDefaultValues(boolean pSettingDefaultValues) set property to true to set default values of the gear definition parameters
void	setSuccessUrl(java.lang.String s)
void	setValues(java.util.Map pValues)

Methods inherited from class atg.portal.admin.PortalGenericFormHandler

addFormException, formatUserMessage, formatUserMessage, formatUserMessage, formatUserMessage, getDefaultLocale, getFailureMessageProcessor, getFailureURL, getFormError, getFormInfo, getFormMessages, getLocale, getPublisher, getSuccessMessageProcessor, getSuccessURL, getUserLocale, handleResetFormExceptions, handleResetFormMessages, handleSetLocale, isUseRequestLocale, processException, processException, processException, processException, processSuccess, processSuccess, processSuccess, resetFormMessages, sendAlertMessage, setDefaultLocale, setFailureMessageProcessor, setFailureURL, setPublisher, setSuccessMessageProcessor, setSuccessURL, setUseRequestLocale

Methods inherited from class atg.droplet.TransactionalFormHandler

afterSet, beforeSet, checkFormRedirect, commitTransaction, getTransactionDemarcation, getTransactionStatus, isEnsureTransaction, isRollbackTransaction, isRollbackTransactionOnUnhandledException, isTransactionMarkedAsRollback, setEnsureTransaction, setRollbackTransaction, setRollbackTransactionOnUnhandledException, setTransactionDemarcation

Methods inherited from class atg.droplet.GenericFormHandler

addUncheckedFormException, createFormSubmissionMessage, getCancelURL, getCheckForValidSession, getFormExceptions, getFormName, getMessagePort, getMessageSource, getMessageType, getPropertyExceptions, getSendMessages, getUncheckedFormExceptions, 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

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

Class version string

Constructor Detail

GearConfigFormHandler

public GearConfigFormHandler()

Method Detail

setParamType

public void setParamType(java.lang.String pParamType)

choices are instance (default) or user

getParamType

public java.lang.String getParamType()

choices are instance (default) or user

setSettingDefaultValues

public void setSettingDefaultValues(boolean pSettingDefaultValues)

set property to true to set default values of the gear definition parameters

isSettingDefaultValues

public boolean isSettingDefaultValues()

if true, then we are setting default values of the gear definition parameters

setValues

public void setValues(java.util.Map pValues)

getValues

public java.util.Map getValues()

setGearIdRequestParameter

public void setGearIdRequestParameter(java.lang.String pGearIdRequestParameter)

getGearIdRequestParameter

public java.lang.String getGearIdRequestParameter()

setCommunityIdRequestParameter

public void setCommunityIdRequestParameter(java.lang.String pCommunityIdRequestParameter)

getCommunityIdRequestParameter

public java.lang.String getCommunityIdRequestParameter()

setGearDefIdRequestParameter

public void setGearDefIdRequestParameter(java.lang.String pGearDefIdRequestParameter)

getGearDefIdRequestParameter

public java.lang.String getGearDefIdRequestParameter()

beforeGet

public void beforeGet(DynamoHttpServletRequest pRequest,
             DynamoHttpServletResponse pResponse)

Calls super.beforeGet() and then enables the transactional form handler management features with setEnsureTransaction(true).

Specified by:

beforeGet in interface DropletFormHandler

Overrides:

beforeGet in class EmptyFormHandler

handleCollectValues

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

This method is intended for collecting the values from the form into the value map. Since that happens automatically this method primarily functions as a debugging method and an opportunity for a developer to subclass and override this method to perform any special processing needed on the values.

Throws:

javax.servlet.ServletException

java.io.IOException

handleCancel

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

Cancel. Clear form values and redirect to cancelURL property (or successURL if cancelURL is not set)

Overrides:

handleCancel in class GenericFormHandler

Throws:

javax.servlet.ServletException

java.io.IOException

handleConfirm

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

Take the values from the value property and set them into the gear environment user or instance parameters.

Throws:

javax.servlet.ServletException

java.io.IOException

preConfirm

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

Override this method to do any pre-processing or verification of form input. Processing will be stopped if there are any errors found. In the extension of this method, if you encounter an error condition, you may use addFailureMessage() or userInfo() to communicate the situation to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

postConfirm

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

Override this method to do any post-processing. Processing will be stopped if there are any errors found. In the extension of this method, if you encounter an error condition, you may use addFailureMessage() or userInfo() to communicate the situation to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

preCollectValues

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

Override this method to do any pre-processing or verification of form input. Processing will be stopped if there are any errors found. In the extension of this method, if you encounter an error condition, you may use addFailureMessage() or userInfo() to communicate the situation to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

postCollectValues

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

Override this method to do any post-processing. Processing will be stopped if there are any errors found. In the extension of this method, if you encounter an error condition, you may use addFailureMessage() or userInfo() to communicate the situation to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

setParamNames

public void setParamNames(java.lang.String pParamNames)

Sets a space delimited list of the names of the gear params that will be set in this form

getParamNames

public java.lang.String getParamNames()

Returns a space delimited list of the names of the gear params that will be set in this form

handleParamNames

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

initialize the default values of the values map property by getting the parameter values out of the gear environment

Throws:

javax.servlet.ServletException

java.io.IOException

getGearEnvironment

protected GearEnvironment getGearEnvironment(DynamoHttpServletRequest pReq,
                                 DynamoHttpServletResponse pResp)

sets up the gear environment.

getSuccessUrl

public java.lang.String getSuccessUrl()

setSuccessUrl

public void setSuccessUrl(java.lang.String s)

getFailureUrl

public java.lang.String getFailureUrl()

setFailureUrl

public void setFailureUrl(java.lang.String s)

getCancelUrl

public java.lang.String getCancelUrl()

setCancelUrl

public void setCancelUrl(java.lang.String s)

handleInitializeDefaultValues

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

Throws:

javax.servlet.ServletException

java.io.IOException

setInitializeDefaultValues

public void setInitializeDefaultValues(java.lang.String s)

addFailureMessage

public void addFailureMessage(java.lang.String pResourceBundle,
                     java.lang.String pMsgId,
                     java.lang.String[] pArgs)
                       throws javax.servlet.ServletException,
                              java.io.IOException

Set a form processing error message that should be visible to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

addSuccessMessage

public void addSuccessMessage(java.lang.String pResourceBundle,
                     java.lang.String pMsgId,
                     java.lang.String[] pArgs)
                       throws javax.servlet.ServletException,
                              java.io.IOException

Set a form processing info message that should be visible to the user.

Throws:

javax.servlet.ServletException

java.io.IOException

isSettingUserParams

public boolean isSettingUserParams()

convenience method to determine if we are setting user params or instance params