hirondelle.web4j.action
Class ActionImpl

Object
  hirondelle.web4j.action.ActionImpl

All Implemented Interfaces:

Action

Direct Known Subclasses:

ActionTemplateListAndEdit, ActionTemplateSearch, ActionTemplateShowAndApply

public abstract class ActionImpl
extends Object
implements Action

Abstract Base Class (ABC) for implementations of the Action interface.

This ABC provides concise methods for common operations, which will make implementations read more clearly, concisely, and at a higher level of abstraction.

A simple fetch-and-display operation can often be implemented using this class as a base class. However, operations involving user input and/or edits to the datastore should very likely use other abstract base classes, such as ActionTemplateListAndEdit, ActionTemplateSearch, and ActionTemplateShowAndApply.

The methods of this class take a liberal approach to session creation. If a method requires that a session exist, then one is created if it does not already exist.

Design note :
The liberal creation of sessions in somewhat distasteful, since sessions represent extra work for the server, and should be minimized if possible. However, some points in favour of this style are :

• the JSTL already creates sessions liberally
• the majority of web applications require user sign-in anyway, which will also create a session
• it is a nice feature to inform the user of a successful edit to the datastore. However, successful edits usually need a redirect to avoid the duplicate-upon-browser-reload problem. The only way to allow dynamic messages to survive a redirect seems to be through sessions.

Field Summary

static String	ERRORS Value "web4j_key_for_errors" - identifies a MessageList, placed in session scope, to hold error information for the end user.
static String	ITEM_FOR_EDIT Value "itemForEdit" - generic key for an object placed in scope for a JSP.
static String	ITEMS_FOR_LISTING Value "itemsForListing" - generic key for a collection of objects placed in scope for a JSP.
static String	MESSAGES Value "web4j_key_for_messages" - identifies a MessageList, placed in session scope, to hold messages for the end user.

Constructor Summary

protected

ActionImpl(ResponsePage aNominalPage, RequestParser aRequestParser) Constructor.

Method Summary

protected void	addError(AppException aEx) Add all the error messages attached to aEx.
protected void	addError(String aMessage) Add a simple AppResponseMessage describing a failed validation of user input, or a failed datastore operation.
protected void	addError(String aMessage, Object... aParams) Add a compound AppResponseMessage describing a failed validation of user input, or a failed datastore operation.
protected void	addMessage(String aMessage) Add a simple AppResponseMessage, to be displayed to the end user.
protected void	addMessage(String aMessage, Object... aParams) Add a compound AppResponseMessage, to be displayed to the end user.
protected void	addToRequest(String aName, Object aObject) Add a name-object pair to request scope.
protected void	addToSession(String aName, Object aObject) Add a name-object pair to the session.
protected void	copyFromSessionToRequest(String aName) Place an object which is in session scope into request scope as well.
protected void	createSession() If a session does not already exist, then create one.
protected void	endSession() If a session exists, then it is invalidated.
abstract ResponsePage	execute() Execute desired operation.
protected MessageList	getErrors() Return all the errors passed to all addError methods.
protected Object	getFromSession(String aName) Retrieve an object from the session, or null if no object is paired with aName.
protected Id	getIdParam(RequestParameter aReqParam) Convenience method for retrieving a parameter as a simple Id.
protected Locale	getLocale() Return the Locale associated with the underlying request.
protected SafeText	getLoggedInUserName() Return the name of the logged in user.
protected MessageList	getMessages() Return all messages passed to all addMessage methods
protected Operation	getOperation() Return the Operation associated with this Action, if any.
protected DynamicCriteria	getOrderBy(RequestParameter aSortColumn, RequestParameter aOrder, String aDefaultOrderBy) Return an ORDER BY clause for an SQL statement.
protected String	getParam(RequestParameter aReqParam) Convenience method for retrieving a parameter as a simple String.
protected RequestParser	getRequestParser() Return the RequestParser passed to the constructor.
ResponsePage	getResponsePage() Return the resource which will render the final result.
protected boolean	hasErrors() Return true only if at least one addError method has been called.
protected void	removeFromSession(String aName) Synonym for addToSession(aName, null).
protected void	setResponsePage(ResponsePage aNewResponsePage) Called by subclasses if the final ResponsePage differs from the nominal one passed to the constructor.

Methods inherited from class Object

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

Field Detail

ERRORS

public static final String ERRORS

Value "web4j_key_for_errors" - identifies a MessageList, placed in session scope, to hold error information for the end user. These errors are used by both WEB4J and the application programmer.

See Also:

Constant Field Values

MESSAGES

public static final String MESSAGES

Value "web4j_key_for_messages" - identifies a MessageList, placed in session scope, to hold messages for the end user. These messages are used by both WEB4J and the application programmer. They typically hold success and information messages.

See Also:

Constant Field Values

ITEM_FOR_EDIT

public static final String ITEM_FOR_EDIT

Value "itemForEdit" - generic key for an object placed in scope for a JSP.

Not mandatory to use this generic key. Provided simply as a convenience.

See Also:

Constant Field Values

ITEMS_FOR_LISTING

public static final String ITEMS_FOR_LISTING

Value "itemsForListing" - generic key for a collection of objects placed in scope for a JSP.

Not mandatory to use this generic key. Provided simply as a convenience.

See Also:

Constant Field Values

Constructor Detail

ActionImpl

protected ActionImpl(ResponsePage aNominalPage,
                     RequestParser aRequestParser)

Constructor.

This constructor will add an attribute named 'Operation' to the request. Its value is deduced as specified by getOperation(). This attribute is intended for JSPs, which can use it to access the Operation regardless of its original source.

Parameters:

aNominalPage - simply one of the possible ResponsePages, arbitrarily chosen as a "default". It may be changed after construction by calling setResponsePage(hirondelle.web4j.action.ResponsePage). Recommended that the "success" page be chosen as the nominal page. If not, then selection of any of the possible ResponsePages is acceptable.

aRequestParser - allows parsing of request parameters into higher level java objects.

Method Detail

execute

public abstract ResponsePage execute()
                              throws AppException

Description copied from interface: Action

Execute desired operation.

Typical operations include :

• validate user input
• interact with the database
• place required objects in the appropriate scope
• set the appropriate ResponsePage.

  Returns an identifier for the resource (for example a JSP) which will display the end result of this Action (using either a forward or a redirect).

  Specified by:

  execute in interface Action

  Throws:

  AppException

getOperation

protected final Operation getOperation()

Return the Operation associated with this Action, if any.

The Operation is found as follows :

1. if there is a request parameter named 'Operation', and it has a value, pass its value to Operation.valueFor(String)
2. if the above style fails, then the extension is examined. For example, a request to .../MyAction.list?x=1 would result in Operation.List being added to request scope, since the extension value list is known to Operation.valueFor(String). This style is useful for implementing fine-grained <security-constraint> items in web.xml. See the User Guide for more information.
3. if both of the above methods fail, return null

getResponsePage

public final ResponsePage getResponsePage()

Return the resource which will render the final result.

setResponsePage

protected final void setResponsePage(ResponsePage aNewResponsePage)

Called by subclasses if the final ResponsePage differs from the nominal one passed to the constructor.

If an implementation calls this method, it is usually called in execute().

addToRequest

protected final void addToRequest(String aName,
                                  Object aObject)

Add a name-object pair to request scope.

If the pair already exists, it is updated with aObject.

Parameters:

aName - satisfies Util.textHasContent(java.lang.String).

aObject - if null and a corresponding name-object pair exists, then the pair is removed from request scope.

createSession

protected final void createSession()

If a session does not already exist, then create one.

addToSession

protected final void addToSession(String aName,
                                  Object aObject)

Add a name-object pair to the session.

If a session does not already exist, then it is created.

If the pair already exists, it is updated with aObject.

Parameters:

aName - satisfies Util.textHasContent(java.lang.String).

aObject - if null and a corresponding name-object pair exists, then the pair is removed from session scope.

removeFromSession

protected final void removeFromSession(String aName)

Synonym for addToSession(aName, null).

getFromSession

protected final Object getFromSession(String aName)

Retrieve an object from the session, or null if no object is paired with aName.

Creates a session if one does not already exist.

Parameters:

aName - satisfies Util.textHasContent(java.lang.String).

copyFromSessionToRequest

protected final void copyFromSessionToRequest(String aName)

Place an object which is in session scope into request scope as well.

When serving the last page in a session, some session items may still be needed for rendering the final page.

For example, a log off page in a mutlilingual application might present a "goodbye" message in the language that the user was using. Since the session is being destroyed, the Locale stored in the session must be first copied into request scope before the session is killed.

Creates a session if one does not already exist.

Parameters:

aName - identifies an Object which is currently in session scope, and satisfies Util.textHasContent(java.lang.String). If no attribute of the given name is found in the current session, then a null is added to the request scope under this name.

endSession

protected final void endSession()

If a session exists, then it is invalidated.

addError

protected final void addError(String aMessage)

Add a simple AppResponseMessage describing a failed validation of user input, or a failed datastore operation.

One of the addError methods must be called when a failure occurs.

addError

protected final void addError(String aMessage,
                              Object... aParams)

Add a compound AppResponseMessage describing a failed validation of user input, or a failed datastore operation.

One of the addError methods must be called when a failure occurs.

addError

protected final void addError(AppException aEx)

Add all the error messages attached to aEx.

One of the addError methods must be called when a failure occurs.

getErrors

protected final MessageList getErrors()

Return all the errors passed to all addError methods.

hasErrors

protected final boolean hasErrors()

Return true only if at least one addError method has been called.

addMessage

protected final void addMessage(String aMessage)

Add a simple AppResponseMessage, to be displayed to the end user.

addMessage

protected final void addMessage(String aMessage,
                                Object... aParams)

Add a compound AppResponseMessage, to be displayed to the end user.

getMessages

protected final MessageList getMessages()

Return all messages passed to all addMessage methods

getLocale

protected final Locale getLocale()

Return the Locale associated with the underlying request.

The configured implementation of LocaleSource defines how Locale is looked up.

getRequestParser

protected final RequestParser getRequestParser()

Return the RequestParser passed to the constructor.

getLoggedInUserName

protected final SafeText getLoggedInUserName()

Return the name of the logged in user.

By definition in the servlet specification, a successfully logged in user will have a non-null return value for HttpServletRequest.getUserPrincipal().

If the user is not logged in, this method will return null.

This method returns SafeText, not a String. The user name is often rendered in the view. Since in general the user name may contain special characters, it is appropriate to model it as SafeText.

getIdParam

protected final Id getIdParam(RequestParameter aReqParam)

Convenience method for retrieving a parameter as a simple Id.

Synonym for getRequestParser().toId(RequestParameter).

getParam

protected final String getParam(RequestParameter aReqParam)

Convenience method for retrieving a parameter as a simple String.

Synonym for getRequestParser().toString(RequestParameter).

getOrderBy

protected final DynamicCriteria getOrderBy(RequestParameter aSortColumn,
                                           RequestParameter aOrder,
                                           String aDefaultOrderBy)

Return an ORDER BY clause for an SQL statement.

Provided as a convenience for the common task of creating an ORDER BY clause from request parameters.

Parameters:

aSortColumn - carries a ResultSet column identifer, either a numeric column index, or the name of the column itself.

aOrder - carries the value ASC or DESC (ignores case).

aDefaultOrderBy - default text to be used if the request parameters are not present, or have no content.