hirondelle.web4j.request
Class RequestParser

Object
  hirondelle.web4j.request.RequestParser

Direct Known Subclasses:

RequestParserImpl

public abstract class RequestParser
extends Object

Abstract Base Class (ABC) for mapping a request to an Action.

See the BuildImpl for important information on how this item is configured.

Almost all concrete implementations of this Abstract Base Class will need to implement only a single method - getWebAction(). WEB4J provides a default implementation RequestParserImpl.

The role of this class is to view the request at a higher level than the underlying Servlet API. In particular, its services include :

• mapping a request to an Action
• parsing request parameters into common "building block" objects (and Collections thereof), such as Date, BigDecimal and so on, using the configured implementation of ConvertParam. (The application programmer will usually use ModelFromRequest to build Model Objects.)

File upload parameters are not returned by this class. Such parameters must be examined in an Action. The Servlet API before version 3.0 of the specification has poor support for file upload parameters, and use of a third party tool is recommended.

The various toXXX methods are offered as a convenience for accessing String and String-like data. All such toXXX methods apply the filtering (and possible preprocessing) performed by ConvertParam.

Constructor Summary

RequestParser(HttpServletRequest aRequest, HttpServletResponse aResponse)
Constructor called by subclasses.

Method Summary

static RequestParser	getInstance(HttpServletRequest aRequest, HttpServletResponse aResponse) Return the configured concrete instance of this Abstract Base Class.
String	getRawParamValue(RequestParameter aReqParam) Return the parameter value exactly as it appears in the request.
String[]	getRawParamValues(RequestParameter aReqParam) Return a multi-valued parameter's values exactly as they appear in the request.
HttpServletRequest	getRequest() Return the underlying request.
HttpServletResponse	getResponse() Return the response associated with the underlying request.
abstract Action	getWebAction() Map a given request to a corresponding Action.
boolean	isFileUploadRequest() Return true only if the request is a POST, and has content type starting with multipart/form-data.
Id	toId(RequestParameter aReqParam) Return a single-valued request parameter as an Id.
Collection<Id>	toIds(RequestParameter aReqParam) Return a multi-valued request parameter as a Collection<Id>.
SafeText	toSafeText(RequestParameter aReqParam) Return a single-valued request parameter as SafeText.
Collection<SafeText>	toSafeTexts(RequestParameter aReqParam) Return a multi-valued request parameter as a Collection<SafeText>.
<T> T	toSupportedObject(RequestParameter aReqParam, Class<T> aSupportedTargetClass) Return a building block object.
<T> List<T>	toSupportedObjects(RequestParameter aReqParam, Class<T> aSupportedTargetClass) Return an ummodifiable List of building block objects.

Methods inherited from class Object

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

Constructor Detail

RequestParser

public RequestParser(HttpServletRequest aRequest,
                     HttpServletResponse aResponse)

Constructor called by subclasses.

Method Detail

getInstance

public static RequestParser getInstance(HttpServletRequest aRequest,
                                        HttpServletResponse aResponse)

Return the configured concrete instance of this Abstract Base Class.

See the BuildImpl for important information on how this item is configured.

getWebAction

public abstract Action getWebAction()
                             throws BadRequestException

Map a given request to a corresponding Action.

The mapping is determined entirely by concrete subclasses, and must be implemented by the application programmer. RequestParserImpl is provided as a default implementation, and is very likely adequate for most applications.

If the incoming request does not map to a known Action, then throw a BadRequestException. Such requests are expected only for bugs and for malicious attacks, and never as part of the normal operation of the program.

Throws:

BadRequestException

getRawParamValue

public final String getRawParamValue(RequestParameter aReqParam)

Return the parameter value exactly as it appears in the request.

Can return null values, empty values, values containing only whitespace, and values equal to the IgnorableParamValue configured in web.xml.

getRawParamValues

public final String[] getRawParamValues(RequestParameter aReqParam)

Return a multi-valued parameter's values exactly as they appear in the request.

Can return null values, empty values, values containing only whitespace, and values equal to the IgnorableParamValue configured in web.xml.

toSupportedObject

public <T> T toSupportedObject(RequestParameter aReqParam,
                               Class<T> aSupportedTargetClass)
                    throws ModelCtorException

Return a building block object.

Uses all methods of the configured implementation of ConvertParam.

Parameters:

aReqParam - underlying request parameter

aSupportedTargetClass - must be supported - see ConvertParam.isSupported(Class)

Throws:

ModelCtorException

toSupportedObjects

public <T> List<T> toSupportedObjects(RequestParameter aReqParam,
                                      Class<T> aSupportedTargetClass)
                           throws ModelCtorException

Return an ummodifiable List of building block objects.

Uses all methods of the configured implementation of ConvertParam.

Design Note
List is returned here since HTML specs state that browsers submit param values in the order of appearance of the corresponding controls in the web page.

Parameters:

aReqParam - underlying request parameter

aSupportedTargetClass - must be supported - see ConvertParam.isSupported(Class)

Throws:

ModelCtorException

toSafeText

public final SafeText toSafeText(RequestParameter aReqParam)

Return a single-valued request parameter as SafeText.

toSafeTexts

public final Collection<SafeText> toSafeTexts(RequestParameter aReqParam)

Return a multi-valued request parameter as a Collection<SafeText>.

toId

public final Id toId(RequestParameter aReqParam)

Return a single-valued request parameter as an Id.

toIds

public final Collection<Id> toIds(RequestParameter aReqParam)

Return a multi-valued request parameter as a Collection<Id>.

getRequest

public final HttpServletRequest getRequest()

Return the underlying request.

getResponse

public final HttpServletResponse getResponse()

Return the response associated with the underlying request.

isFileUploadRequest

public final boolean isFileUploadRequest()

Return true only if the request is a POST, and has content type starting with multipart/form-data.