net.jspcontrols.dialogs.actions.crud
Class CRUDAction

java.lang.Object
  org.apache.struts.action.Action
      org.apache.struts.actions.DispatchAction
          net.jspcontrols.dialogs.actions.SelectAction
              net.jspcontrols.dialogs.actions.DialogAction
                  net.jspcontrols.dialogs.actions.crud.CRUDAction

All Implemented Interfaces:

IDialogAction, ISelectAction

public class CRUDAction

extends DialogAction

CRUDAction facilitates the processing of the common use case of an interactive application: creation, update and deletion of a business object (BO). Business object is also called item

CRUDAction has the following features:

• Handler methods for CRUD events
• States and state transitions for BO
• Mappings for result pages

These features are ihnerited from DialogAction:

• Event-based input handling
• Two-phase I/O processing (POST-redirect-GET)
• Buffering and removal of error messages
• Safe use of Reload browser button
• Improved protection from double submits
• Cleaner browser page history

CRUDAction has a notion of current item. It is an existing item, which is being viewed or edited, or a new item, which just has been created and is being filled out. In other words, current item is the item we currently working with.

If current item does not exist, CRUDAction is switched to inactive state. It is possible to switch to one of two active states, by doing one of the following:

• Create new item from scratch and start populating its properties.
• Create new item duplicating its data from existing one, and change some of its properties.
• Edit existing item, updating some or all of its properties.
• View existing item in read-only mode.
• Delete existing item.

After we created a new item or started to edit an existing one, CRUDAction switches to one of the active states: editable or readonly. Editable state permits to update item data. Readonly state is used for preview mode and may help to optimize item caching.

CRUDAction must be paired with a form bean, implementing ICRUDForm, to deliver its full power. See sample code for an example of how a concrete CRUDAction can be implemented

Author:

Michael Jouravlev

CRUDAction

public CRUDAction()

getKeyMethodMap

protected java.util.Map getKeyMethodMap()

Maps submit button names to handler methods; also maps initialization keys to initialization methods. Events, external to CRUDAction, are considered initializing events, and therefore must start with initialization prefix. For example, if initialization prefix starts with "DIALOG-EVENT", then "DIALOG-EVENT-CREATE" is a good key for "Create new business object" event, while "DIALOG-EVENT-CREATE" is not.

If you do not want to use all CRUD handlers, and want to protect yourself from calling unneeded handler, you can subclass this class, and override this method. Then you define only mappings that you need.

Overrides:

getKeyMethodMap in class DialogAction

Returns:

Map, containing association between event names (keys) and handler methods (values).

See Also:

SelectAction.getInitKey()

onCreate

public org.apache.struts.action.ActionForward onCreate(org.apache.struts.action.ActionMapping mapping,
                                                       org.apache.struts.action.ActionForm form,
                                                       javax.servlet.http.HttpServletRequest request,
                                                       javax.servlet.http.HttpServletResponse response)
                                                throws java.lang.Exception

Creates new item. Calls associated action form to create new business object and to initialize action form fields. In case of error, messages are saved in the session and removed automatically during render phase.

Returns:

ActionForward object, identifying the target location. Possible values are: CRUDConstants.MAPPING_ON_CREATE_SUCCESS if new business object was created successfully, or CRUDConstants.MAPPING_ON_CREATE_FAILURE if failed to create new business object.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_CREATE_SUCCESS, CRUDConstants.MAPPING_ON_CREATE_FAILURE

onDuplicate

public org.apache.struts.action.ActionForward onDuplicate(org.apache.struts.action.ActionMapping mapping,
                                                          org.apache.struts.action.ActionForm form,
                                                          javax.servlet.http.HttpServletRequest request,
                                                          javax.servlet.http.HttpServletResponse response)
                                                   throws java.lang.Exception

Creates new item based on existing item. Calls associated action form to create new business object and to initialize action form fields, using existing business data. In case of error, messages are saved in the session and removed automatically during render phase.

Returns:

ActionForward object, identifying the target location. Possible values are: CRUDConstants.MAPPING_ON_DUPLICATE_SUCCESS if new business object was created successfully, or CRUDConstants.MAPPING_ON_DUPLICATE_FAILURE if failed to create new business object.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_DUPLICATE_SUCCESS, CRUDConstants.MAPPING_ON_DUPLICATE_FAILURE

onEdit

public org.apache.struts.action.ActionForward onEdit(org.apache.struts.action.ActionMapping mapping,
                                                     org.apache.struts.action.ActionForm form,
                                                     javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response)
                                              throws java.lang.Exception

Updates existing item. Calls associated action form to load existing business object from persistence layer. In case of error, messages are saved in the session and removed automatically during render phase.

Returns:

ActionForward object, identifying the target location. Possible values are: CRUDConstants.MAPPING_ON_EDIT_SUCCESS if existing business object was successfully prepared for editing, or CRUDConstants.MAPPING_ON_LOAD_FAILURE if failed to load existing business object from persistence layer.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_EDIT_SUCCESS, CRUDConstants.MAPPING_ON_LOAD_FAILURE

onPreview

public org.apache.struts.action.ActionForward onPreview(org.apache.struts.action.ActionMapping mapping,
                                                        org.apache.struts.action.ActionForm form,
                                                        javax.servlet.http.HttpServletRequest request,
                                                        javax.servlet.http.HttpServletResponse response)
                                                 throws java.lang.Exception

Previews existing item. Calls associated action form to load existing business object from persistence layer. In case of error, messages are saved in the session and removed automatically during render phase.

Returns:

ActionForward object, identifying the target location. Possible values are: CRUDConstants.MAPPING_ON_NOEDIT_SUCCESS if existing business object was successfully prepared for viewing, or CRUDConstants.MAPPING_ON_LOAD_FAILURE if failed to load existing business object from persistence layer.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_PREVIEW_SUCCESS, CRUDConstants.MAPPING_ON_LOAD_FAILURE

onDelete

public org.apache.struts.action.ActionForward onDelete(org.apache.struts.action.ActionMapping mapping,
                                                       org.apache.struts.action.ActionForm form,
                                                       javax.servlet.http.HttpServletRequest request,
                                                       javax.servlet.http.HttpServletResponse response)
                                                throws java.lang.Exception

Deletes existing item. This is the only event which can be triggered from all three CRUD modes: Inactive, Edit and Noedit. This method calls associated action form to perform actual removal of business object from persistence layer. In case of error, messages are saved in the session and removed automatically during render phase.

Returns:

ActionForward object, identifying the target location. Possible values are: CRUDConstants.MAPPING_ON_DELETE_SUCCESS if existing business object was successfully deleted, or CRUDConstants.MAPPING_ON_DELETE_FAILURE if failed to delete existing business object from persistence layer.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_DELETE_SUCCESS, CRUDConstants.MAPPING_ON_DELETE_FAILURE

onCancel

public org.apache.struts.action.ActionForward onCancel(org.apache.struts.action.ActionMapping mapping,
                                                       org.apache.struts.action.ActionForm form,
                                                       javax.servlet.http.HttpServletRequest request,
                                                       javax.servlet.http.HttpServletResponse response)
                                                throws java.lang.Exception

Cancels filling it new item, or editing existing item without saving it. This method calls associated action form to perform needed cleanup. No messages are generated for this event.

Returns:

ActionForward object, identifying the target location. Created using CRUDConstants.MAPPING_ON_CANCEL mapping.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_CANCEL

onReset

public org.apache.struts.action.ActionForward onReset(org.apache.struts.action.ActionMapping mapping,
                                                      org.apache.struts.action.ActionForm form,
                                                      javax.servlet.http.HttpServletRequest request,
                                                      javax.servlet.http.HttpServletResponse response)
                                               throws java.lang.Exception

Resets form content. This method calls associated action form to perform needed cleanup. No messages are generated for this event.

Returns:

ActionForward object, identifying the target location. Created using CRUDConstants.MAPPING_ON_RESET mapping.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_RESET_SUCCESS, CRUDConstants.MAPPING_ON_RESET_FAILURE

onClose

public org.apache.struts.action.ActionForward onClose(org.apache.struts.action.ActionMapping mapping,
                                                      org.apache.struts.action.ActionForm form,
                                                      javax.servlet.http.HttpServletRequest request,
                                                      javax.servlet.http.HttpServletResponse response)
                                               throws java.lang.Exception

Closes business item preview page. This method calls associated action form to perform needed cleanup. No messages are generated for this event.

Returns:

ActionForward object, identifying the target location. Created using CRUDConstants.MAPPING_ON_CLOSE mapping.

Throws:

java.lang.Exception

See Also:

CRUDConstants.MAPPING_ON_CLOSE

onSave

public org.apache.struts.action.ActionForward onSave(org.apache.struts.action.ActionMapping mapping,
                                                     org.apache.struts.action.ActionForm form,
                                                     javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response)
                                              throws java.lang.Exception

Event handler for Save button, persists form data. Called during input phase of two-phase I/O process.

Internally, this method calls two methods on associated form bean: standard validate method to check input data, and crudStore method to persist input data if it is valid.

Both form bean methods should return non-empty ActionMessages object to signal that either validation or persisting was unsuccessful.

Since this method handles POST requests, the outcome mappings for this method should use redirection to avoid double submit situations and POSTDATA messages.

Parameters:

mapping - The ActionMapping used to select this instance

form - The optional ActionForm bean for this request (if any)

request - The HTTP request we are processing

response - The HTTP response we are creating

Returns:

an ActionForward instance describing where and how control should be handed over, or null to reload the same action using GET request.

Throws:

java.lang.Exception - if an exception occurs

getDialogView

public org.apache.struts.action.ActionForward getDialogView(org.apache.struts.action.ActionMapping mapping,
                                                            org.apache.struts.action.ActionForm form,
                                                            javax.servlet.http.HttpServletRequest request,
                                                            javax.servlet.http.HttpServletResponse response)
                                                     throws java.lang.Exception

Returns an ActionForward instance describing the View for current dialog state, usually a forward to a JSP page.

If you want to use the default implementation, define the View under "DIALOG-VIEW" name in <forward> element of your action mapping.

To use different mapping name, define the view in <forward> element of your action mapping, and override this method to return ActionForward object for your mapping name.

Specified by:

getDialogView in interface IDialogAction

Overrides:

getDialogView in class DialogAction

Parameters:

mapping - The ActionMapping used to select this instance

form - The optional ActionForm bean for this request (if any)

request - The HTTP request we are processing

response - The HTTP response we are creating

Returns:

ActionForward instance describing the View for dialog state

Throws:

java.lang.Exception - if an exception occurs