net.jspcontrols.dialogs.actions
Class SelectAction

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

All Implemented Interfaces:

ISelectAction

Direct Known Subclasses:

DialogAction

public abstract class SelectAction

extends org.apache.struts.actions.DispatchAction

implements ISelectAction

An abstract Action that dispatches a browser event to a handler method. This class allows to process a form submission using either regular submit button or an image button. It works with regular links as well.

• Processes submit events (POST) or link events (GET).
• Handles pushbuttons, image buttons and regular links in universal fashion.
• Does not use parameter attribute of action mapping.
• Allows to set an arbitrary caption for a pushbutton.
• Button caption can be easily changed at runtime.

Technical details

Unlike DispatchAction and LookupDispatchAction classes, which correlate value attribute of submit form element with name of a handler method, this class uses name attribute. This allows to display a user-friendly caption on a submit button and to change button caption without redeployment.

The subclass must define a map, which correlates event names with method names, and handler methods themselves. Events names must be different from names of action form properties. Each method must have the same signature as execute method.

By definition, an event is a request parameter, which starts from a known prefix. The prefix is specified in getInitKey method and can be redefined in a subclass. Default prefix is "DIALOG-EVENT".

If you decide to redifine the event prefix, make sure that it does not contain periods. Also, do not use periods for specific event names. Struts may throw an exception taking the name for nested property and trying to set its value.

Usage

Subclass SelectAction, implement getKeyMethodMap method, and map specific events to method handlers. Event name must start with event prefix:

 protected Map getKeyMethodMap() {
     Map map = new HashMap();
     map.put(getInitKey()+"-ADD", "add");
     map.put(getInitKey()+"-DELETE", "delete");
     map.put(getInitKey()+"-CREATE", "create");
     map.put(getInitKey()+"-LOGIN", "login");
     return map;
 }
 

Remember that standard <html:cancel/> button is implicitly mapped to cancelled method. You need to implement this method to receive cancel events.

Implement handler methods themselves, for example:

 public ActionForward add(ActionMapping mapping,
                          ActionForm form,
                          HttpServletRequest request,
                          HttpServletResponse response)
      throws IOException, ServletException {
      // do add
      return mapping.findForward("success");
 }
 

Use event names in name attribute of submit buttons, or as query paramter for regular links:

 <form action="/selecttest.do" method="post">
     <input type="submit" name="DIALOG-EVENT-ADD" value="Add item"/>
     <input type="submit" name="DIALOG-EVENT-DELETE" value="Delete item"/>
 </form>
 <input type="image" name="DIALOG-EVENT-LOGIN" src="login.gif" value="Log In">
 <a href="/selecttest.do?DIALOG-EVENT-CREATE">Create item</a>
 

Notes

• Subclass does not have to overridere execute method.
• If duplicate values exist for the keys returned by getKeyMethodMap, the first one will be returned. If no corresponding key is found then an exception will be thrown.
• Standard Cancel button must be handled by cancelled method.
• According to HTML specification, at most one submit element is sent from browser to the server when form is submitted. If form is submitted without explicitly clicking a button, the result depends on a browser. Either no buttons are submitted, or the first button defined on the form is submitted. If no butons is submitted, unspecified method is called. Override this method to handle default submits.

Author:

Michael Jouravlev

keyMethodMap

protected java.util.Map keyMethodMap

Map, which correlates events with handler methods

SelectAction

public SelectAction()

resolveEvents

public void resolveEvents(org.apache.struts.action.ActionMapping mapping)

Scans <component> elements of struts-config.xml file and looks up for <event> elements, binding browser events to handler methods. If such declarations found, they are used to build handler mapping, and getKeyMethodMap is not called

Therefore, event mappings have to be defined either declaratively or programmatically but not both.

Parameters:

mapping - ActionMapping from current request

Since:

1.24

buildLookupMap

protected void buildLookupMap()
                       throws javax.servlet.ServletException

Builds an event map. Called only once for each instance of this class. This internal method should not normally be redefined by a subclass.

Throws:

javax.servlet.ServletException

getInitKey

public java.lang.String getInitKey()

Returns the event prefix. All event names must start with this prefix. Override this method if you want to use prefix different than "DIALOG-EVENT"

getDefaultKey

public java.lang.String getDefaultKey()

Name of request parameter, identifying default event. Used to select a request handler for "default submit" by Internet Explorer. If this parameter is not set in request, then unspecified method is called.

getCancelKey

public java.lang.String getCancelKey()

Returns the cancel key.Override this method if you want to use prefix different from "DIALOG-EVENT-CANCEL"

execute

public 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 java.lang.Exception

Process the specified HTTP request, and create the corresponding HTTP response (or forward to another web component that will create it). Return an ActionForward instance describing where and how control should be forwarded, or null if the response has already been completed.

This method should not normally be redefined by a subclass.

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

Throws:

java.lang.Exception - if an exception occurs

execute

public org.apache.struts.action.ActionForward execute(ISelectAction action,
                                                      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

Dispatches to the method on the action instance of Action class. This method should be used when SelectAction is used as utility class. Always create a separate instance of utility SelectAction class for each of your custom action classes.

This method uses portions of code from DispatchAction class.

Parameters:

action - instance of Action class, method of which is about to be called

mapping - Struts action mapping

form - Struts form bean instance

request - request we are processing

response - response we are returning

Returns:

Struts ActionForward object, the same which is regularly returned by an execute method.

Throws:

java.lang.Exception

Since:

1.24

getMethod

protected java.lang.reflect.Method getMethod(java.lang.Object action,
                                             java.lang.String name)
                                      throws java.lang.NoSuchMethodException

Introspect the given action class to identify a method of the specified name that accepts the same parameter types as the execute method does.

This method should not be called directly from user code. This method is used internally by SelectAction when it is used as a helper dispatcher, instantiated in a custom action class.

Parameters:

action - Action class that should be introspected

name - Name of the method to be introspected

Throws:

java.lang.NoSuchMethodException - if no such method can be found

getMethodName

protected java.lang.String getMethodName(org.apache.struts.action.ActionMapping mapping,
                                         org.apache.struts.action.ActionForm form,
                                         javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response,
                                         java.lang.String parameter)
                                  throws java.lang.Exception

Returns the method name, given a request object and event name. This helper method should not normally be redefined by a subclass.

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

parameter - The ActionMapping parameter's name; not used by SelectAction

Returns:

The handler method name if event recognized, or null if event is notrecognized. For unrecognized event DispatchAction will call "unspecified" handler.

Throws:

java.lang.Exception

unspecified

public org.apache.struts.action.ActionForward unspecified(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

A handler method for "default submit" situation, that is when an event is not recognized in a request. Default implementation of this method throws a ServletException.

Override this method to provide different behavior.

Specified by:

unspecified in interface ISelectAction

Throws:

java.lang.Exception

cancelled

public org.apache.struts.action.ActionForward cancelled(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

A handler method for standard Struts Cancel button. Default implementation of this method does nothing and does not throw an exception.

Override this method to provide appropriate behavior.

Specified by:

cancelled in interface ISelectAction

Throws:

java.lang.Exception

getKeyMethodMap

protected abstract java.util.Map getKeyMethodMap()

Provides mapping between event names (keys) and handler methods (values). Do not forget to define handler methods themselves. Each handler method must have the same signature as execute method. To handle <html:cancel/> override cancelled method.

This method must be implemented by a subclass.

Returns:

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