com.boylesoftware.cb2.presentation.servlet
Class CB2Action

java.lang.Object
  org.apache.struts.action.Action
      com.boylesoftware.cb2.presentation.servlet.CB2Action

Direct Known Subclasses:

ShowPageAction

public abstract class CB2Action

extends org.apache.struts.action.Action

Abstract parent class for CB2/Struts action handlers. This class extends Struts' action class functionality and adds such features as action context and database transaction management. Extending this class makes easy to communicate with CB2 business level. In the most cases you will need only to redefine the abstract execute method in your concrete action handler implementation.

Normally, execution of actions is serialized within a session, meaning that if there is an action being executed in its user-defined execute method and a new request comes within the same session, then this new request will wait until the first action is finished. This is implemented through locking the BLO container right before calling the execute method and releasing it right after. This behaviour can be overriden with [detached] action flag (see below).

Unless [noTX] (see below) is specified, on redefined doAutoTransaction method returns false, a database transaction will be started before calling execute method. If the execute returns successfully and does not throw any exception, the transaction will be committed right after its return. If it throws an exception the transaction will be automatically rolled back.

You can specify special flags and pass them to the action with parameter attribute of the corresponding action element in the struts-config.xml. Here is an example:

 <action
   path="/app/addRecord"
   type="my.application.actions.GotoAction"
   parameter="[noTX][detached]">
   <forward name="success" path="addRecordForm"/>
 </action>

This implementation recognizes the following flags:

• [noTX] - do not automatically manage database transaction for the action. Usually you specify this flag for actions that do not do anything with the database (through BLOs). Note, that there is an alternative way to enable/disable automatic transaction handling for an action: you can override the doAutoTransaction method in your action implementation. The [noTX] then will be ignored.
• [detached] - do not aquire and lock the BLO container for this action. The bloContainer property (getBLOContainer() method on the ActionContext) in the action context passed to to the execute method will be null. You still can get access to shared BLOs through the getSharedBLO protected method. This flag is useful in situation when you need a long running action. Since normally actions are executed sequencially with the BLO container locking, it is highly recommended to keep your actions as "short" as possible, so they release the BLO container as soon as possible after they lock it. Now, sometimes, you need an action that performes a long and complex operation. Then you declare this action "detached" and it won't have access to the session's BLO container and thus won't lock it. If you need any data from business level, which is not provided by your shared BLOs, you should fetch all that data in advance in a regular action and then pass it to the "detached" action in an application dependent manner. Note also, that you can achieve the effect of this flag by redefining the isDetached method in your action implementation.

Sometimes when multiple requests are being processed for the same session, one of the actions may destroy the session (for example user requested logout from a browser window while request is still being processed in another window). If this happens and the action cannot get BLO container, because it was just destroyed, a special forward named "nosession" is found and returned by the action without calling user defined execute method. If no "nosession" forward is defined an exception is thrown by the action. Note also, that the action enforces "redirect" flag on the "nosession" forward.

Version:

$Id: CB2Action.java,v 1.14 2004/04/08 18:32:23 levahim Exp $

Author:

Lev Himmelfarb

Field Summary

Fields inherited from class org.apache.struts.action.Action

ACTION_SERVLET_KEY, APPLICATION_KEY, DATA_SOURCE_KEY, defaultLocale, ERROR_KEY, EXCEPTION_KEY, FORM_BEANS_KEY, FORWARDS_KEY, LOCALE_KEY, MAPPING_KEY, MAPPINGS_KEY, MESSAGE_KEY, MESSAGES_KEY, MULTIPART_KEY, PLUG_INS_KEY, REQUEST_PROCESSOR_KEY, servlet, SERVLET_KEY, TRANSACTION_TOKEN_KEY

Constructor Summary

CB2Action()

Method Summary

protected boolean	doAutoTransaction(javax.servlet.http.HttpServletRequest request, java.lang.String mappingParameter) Checks if [noTX] flag is specified in the action mapping parameter and tells whether an automatic transaction should be handled for the action.
protected abstract org.apache.struts.action.ActionForward	execute(ActionContext actionCtx) Redefine this method in your child action handler.
org.apache.struts.action.ActionForward	execute(org.apache.struts.action.ActionMapping mapping, org.apache.struts.action.ActionForm form, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) CB2 implementation of the Struts' action execute method.
protected java.lang.String	getActionName() Returns this action implementation's logical name.
protected java.lang.Integer	getParameterAsInt(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Retreives a request parameter as an int number.
protected int	getParameterAsIntNoNull(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Retreives a request parameter as an int number.
protected java.lang.Long	getParameterAsLong(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Retreives a request parameter as a long number.
protected long	getParameterAsLongNoNull(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Retreives a request parameter as a long number.
protected java.lang.String	getParameterNoNull(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Checks if a parameter is in a request and returns its value if so.
protected boolean	isDetached(javax.servlet.http.HttpServletRequest request, java.lang.String mappingParameter) Checks if [detached] flag is specified in the action mapping parameter and tells whether the session's BLO container should be aquired and locked for the action execution.
protected boolean	isValidEmailAddress(java.lang.String value) Deprecated. use TextUtils.isValidEmailAddress(java.lang.String) static method instead.
protected boolean	isValidUSPhoneNumber(java.lang.String value) Deprecated. no direct replacement for this method, should be implemented in the application specific way.
protected void	logout(ActionContext actionCtx) Logs out the currently authenticated in user.

Methods inherited from class org.apache.struts.action.Action

execute, generateToken, getDataSource, getDataSource, getLocale, getResources, getResources, getResources, getServlet, isCancelled, isTokenValid, isTokenValid, perform, perform, resetToken, saveErrors, saveMessages, saveToken, setLocale, setServlet, toHex

Methods inherited from class java.lang.Object

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

Constructor Detail

CB2Action

public CB2Action()

Method Detail

execute

public final org.apache.struts.action.ActionForward execute(org.apache.struts.action.ActionMapping mapping,
                                                            org.apache.struts.action.ActionForm form,
                                                            javax.servlet.http.HttpServletRequest request,
                                                            javax.servlet.http.HttpServletResponse response)
                                                     throws javax.servlet.ServletException,
                                                            java.io.IOException

CB2 implementation of the Struts' action execute method. It prepares an action context and calls user-defined execute(ActionContext actionCtx) method internally. It also manages a database transaction if required.

Parameters:

mapping - the action mapping used to select this instance.

form - form bean instance for this request. May be null if no form is associated with this action in the mapping.

request - the HTTP request.

response - the HTTP response.

Throws:

javax.servlet.ServletException - if an error happened in the action.

java.io.IOException - if an input/output error happened in the action.

execute

protected abstract org.apache.struts.action.ActionForward execute(ActionContext actionCtx)
                                                           throws BLException,
                                                                  javax.servlet.ServletException,
                                                                  java.io.IOException

Redefine this method in your child action handler. It will be called by the framework for each request mapped to this action in the struts-config.xml configuration file.

Parameters:

actionCtx - action context.

Throws:

BLException - if an error happened in the business level. Usually it is an exception thrown by a BLO called from within the action.

javax.servlet.ServletException - if an error happened in the action.

java.io.IOException - if an input/output error happened in the action.

getActionName

protected java.lang.String getActionName()

Returns this action implementation's logical name. The default implementation returns null.

By default the log passed to the user-defined execute method with the action context is set to "com.boylesoftware.cb2.ACTION" subsystem name. You can redefine this method to return name which will be added to this prefix after an additional dot to form subsystem name for the logger. This allows you to have a different log configuration, such as verbosity, on per action level.

Returns:

action name. This implementation returns null.

doAutoTransaction

protected boolean doAutoTransaction(javax.servlet.http.HttpServletRequest request,
                                    java.lang.String mappingParameter)

Checks if [noTX] flag is specified in the action mapping parameter and tells whether an automatic transaction should be handled for the action.

You can redefine this method in your action implementation to involve some other mechanism of telling whether the trasaction should be handled automatically or not.

Parameters:

request - current request, the default implementation ignores this parameter.

mappingParameter - value of the Struts action mapping's parameter attribute from the struts-config.xml file. May be null.

Returns:

true if the action shuold be executed in a transaction. This implementation returns true by default when the mappingParameter argument is null or does not contain [noTX] substring.

isDetached

protected boolean isDetached(javax.servlet.http.HttpServletRequest request,
                             java.lang.String mappingParameter)

Checks if [detached] flag is specified in the action mapping parameter and tells whether the session's BLO container should be aquired and locked for the action execution.

You can redefine this method in your action implementation to involve some other mechanism of telling whether the action should be "detached" or not.

Parameters:

request - current request, the default implementation ignores this parameter.

mappingParameter - value of the Struts action mapping's parameter attribute from the struts-config.xml file. May be null.

Returns:

true if the action should be "detached". This implementation returns false by default when the mappingParameter argument is null and it returns true if the mappingParameter is not null and contains [detached] substring.

logout

protected final void logout(ActionContext actionCtx)

Logs out the currently authenticated in user. Calling this method also results in the HTTP session invalidation at the end of the request processing. If there is no authenticated user this method still invalidates the session.

Parameters:

actionCtx - the action context.

isValidEmailAddress

protected boolean isValidEmailAddress(java.lang.String value)

Deprecated. use TextUtils.isValidEmailAddress(java.lang.String) static method instead.

Checks if the specified value is a valid email address.

Parameters:

value - form field value to check.

Returns:

true if the specified string is not null and is a valid email address (synthax-wise).

isValidUSPhoneNumber

protected boolean isValidUSPhoneNumber(java.lang.String value)

Deprecated. no direct replacement for this method, should be implemented in the application specific way.

Checks if the specified value is a valid US phone number.

Parameters:

value - form field to check.

Returns:

true if the specified string is not null and is a valid US phone number.

getParameterNoNull

protected java.lang.String getParameterNoNull(javax.servlet.http.HttpServletRequest request,
                                              java.lang.String paramName)
                                       throws javax.servlet.ServletException

Checks if a parameter is in a request and returns its value if so. Otherwise, throws an exception.

Parameters:

request - HTTP request to get the parameter from.

paramName - name of the request parameter.

Returns:

the specified parameter's value.

Throws:

javax.servlet.ServletException - if the specified parameter is not present in the specified request.

getParameterAsLong

protected java.lang.Long getParameterAsLong(javax.servlet.http.HttpServletRequest request,
                                            java.lang.String paramName)
                                     throws javax.servlet.ServletException

Retreives a request parameter as a long number.

Parameters:

request - HTTP request to get the parameter from.

paramName - name of the request parameter.

Returns:

the specified parameter's value as a long number or null if the parameter is not present in the request or its value is empty.

Throws:

javax.servlet.ServletException - if the specified parameter is present in the request but it is not a valid long number.

getParameterAsLongNoNull

protected long getParameterAsLongNoNull(javax.servlet.http.HttpServletRequest request,
                                        java.lang.String paramName)
                                 throws javax.servlet.ServletException

Retreives a request parameter as a long number.

Parameters:

request - HTTP request to get the parameter from.

paramName - name of the request parameter.

Returns:

the specified parameter's value as a long number.

Throws:

javax.servlet.ServletException - if the specified parameter is not present in the request or it is not a valid long number.

getParameterAsInt

protected java.lang.Integer getParameterAsInt(javax.servlet.http.HttpServletRequest request,
                                              java.lang.String paramName)
                                       throws javax.servlet.ServletException

Retreives a request parameter as an int number.

Parameters:

request - HTTP request to get the parameter from.

paramName - name of the request parameter.

Returns:

the specified parameter's value as an int number or null if the parameter is not present in the request or its value is empty.

Throws:

javax.servlet.ServletException - if the specified parameter is present in the request but it is not a valid int number.

getParameterAsIntNoNull

protected int getParameterAsIntNoNull(javax.servlet.http.HttpServletRequest request,
                                      java.lang.String paramName)
                               throws javax.servlet.ServletException

Retreives a request parameter as an int number.

Parameters:

request - HTTP request to get the parameter from.

paramName - name of the request parameter.

Returns:

the specified parameter's value as an int number.

Throws:

javax.servlet.ServletException - if the specified parameter is not present in the request or it is not a valid int number.