com.sas.actionprovider
Class HttpActionProvider

com.sas.actionprovider.HttpActionProvider

All Implemented Interfaces:

com.sas.collection.ContentsChangedSource

public class HttpActionProvider
implements com.sas.collection.ContentsChangedSource

The HttpActionProvider class, in conjunction with other parts of the ActionProvider Framework (APF), is used by Transformation Beans as a mechanism for acquiring renderable Actions for specific viewable areas of the component.

A basic understanding of the ActionProvider Framework, of which this class is a part, is recommended before attempting to use this class.

• For general information on the ActionProvider Framework, including an overview of how the primary classes of the framework work together, refer to the com.sas.actionprovider package documentation.

• For examples demonstrating how to use the ActionProvider Framework, including how to override default Actions or add new custom Actions, refer to the Samples Site.

Components that implement the HttpActionProviderViewInterface may query a HttpActionProvider for Actions via its getActions() method.

The acquired Actions encapsulate the information needed by the component to represent the Action visually and to have its associated command, when present, executed.

Additionally, this class allows users to customize the Actions available to a particular component type or instance.

Most implementations of HttpActionProviderViewInterface require that an instance of the HttpActionProvider be set on them:

HttpActionProvider ap = new HttpActionProvider();

((HttpActionProviderViewInterface)viewer).setActionProvider(ap);

Visit the AppDev Studio Developer's Site to access step-by-step examples, white papers and additional usage information at http://support.sas.com/rnd/appdev/.

Note: A snapshot of the AppDev Studio Developers Site is installed on your local Web server when you install AppDev Studio. To access the site from webAF, select Help -> Developer Site .

Since:

3.0

See Also:

HttpAction, HttpActionProviderViewInterface

Field Summary

static java.lang.String	AJAX_CONTROLLER_URL Key used with url template substitution when mapping to the ajax controller url specified on the viewer component.
static java.lang.String	ALL_VIEWERS Key used when flushing references to all viewers from this HttpActionProvider.
static java.lang.String	APNAME Key used with url template substitution when mapping to the name of this HttpActionProvider.
static java.lang.String	BASEURL Key used with url template substitution when mapping to the base of the url string that gets generated from the attributes of an HttpAction.
static java.lang.String	CMDID Key used with url template substitution when mapping to the unique identifier of a command instance stored on this HttpActionProvider.
static java.lang.String	CONTEXTPATH Key used with url template substitution when mapping to the request context path.
static java.lang.String	DYNAMICATTRS Key used with url template substitution when mapping to the url query string that gets generated from the attributes of an HttpAction.
static java.lang.String	PARMPREFIX Key used when mapping to the parameterPrefix attribute of this HttpActionProvider.
static java.lang.String	QUERYSTRING Key used with url template substitution when mapping to the Action Provider related parameters associated with an Action.
static java.lang.String	REFERRING_URI_PARAMETER Key used to name the request parameter that holds the uri of the referring request.
static java.lang.String	REFERRINGURI Key used with url template substitution when mapping to the original URI of the viewer.
static java.lang.String	REFRESH_VIEWER_ID_PARAMETER Key used to name the request parameter that holds the id of the viewer component that queries for an Action.
static java.lang.String	REFRESHVIEWERID Key used with url template substitution when mapping to the id of the viewer that will be refreshed when after the action is performed.
static java.lang.String	VIEWER_ID_PARAMETER Key used to name the request parameter that holds the id of the viewer component that queries for an Action.
static java.lang.String	VIEWERID Key used with url template substitution when mapping to the id of viewer component.

Constructor Summary

HttpActionProvider()
Default constructor

Method Summary

void	addExternalRequestParameter(HttpActionProviderViewInterface viewer, java.lang.String parameterName, java.lang.String parameterValue) Adds a key/value pair of request parameters to be included on all Actions returned by this ActionProvider.
void	addExternalRequestParameters(HttpActionProviderViewInterface viewer, java.util.Map externalParameters) Adds multiple key/value pairs of request parameters to be included on the actions returned by this action provider.
void	applyCommandAttributes(javax.servlet.http.HttpServletRequest request, DynamicAttributeCommandInterface command) Applies command attributes that are on the request or are stored on this ActionProvider.
void	executeCommand(DynamicAttributeCommandInterface command, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object obj) Executes the command.
DynamicAttributeCommandInterface	executeCommand(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object obj) Executes the command associated with the CMDID parameter on the HttpServletRequest.
void	fireContentsChanged(ActionProviderEvent event) Send a ActionProviderEvent event to all the ContentsChangedListener objects in the listener list.
void	flush(java.lang.Object viewer) Flushes all internal objects held for the specified viewer object.
java.lang.String	getControllerURL() Returns the url of a central controller or generic handler.
DynamicAttributeCommandInterface	getExecutableCommand(javax.servlet.http.HttpServletRequest request) Returns an executable copy of the command object referred to by the CMDID parm on the request object and that is stored on the ActionProvider.
java.util.Map	getExternalRequestParameters() Returns a map of all the key/value pairs to be included on every action returned by this action provider.
java.util.Map	getExternalRequestParameters(HttpActionProviderViewInterface viewer) Returns a map of all the key/value pairs to be included on every action returned by this action provider for a specific viewer.
java.lang.String	getParameterPrefix() Returns the prefix that is prepended to the names of all non-external request parameters.
java.util.Map	getRequestCommandAttributes(javax.servlet.http.HttpServletRequest request) Returns a Map of all the request parameters that match properties on the command.
java.util.Map	getStoredCommandAttributes(javax.servlet.http.HttpServletRequest request) Returns a copy of the Map of stored attributes that is associated with the CMDID parameter on the request object.
boolean	getUseReferringURIParameter() Return the boolean indicating whether a REFERRING_URI_PARAMETER is set on all actions returned by this action provider.
void	setControllerURL(java.lang.String controllerURL) Sets the url of a central controller or generic handler.
void	setParameterPrefix(java.lang.String parameterPrefix) Sets the prefix that is prepended to the names of all non-external request parameters.
void	setUseReferringURIParameter(boolean useReferringURIParameter) Sets the boolean indicating whether a REFERRING_URI_PARAMETER should be set on all Actions returned by this action provider.
java.lang.String	storeCommand(DynamicAttributeCommandInterface command, java.lang.Object viewer, java.util.Map storedProperties) Stores the command on this HttpActionProvider.

Methods inherited from class com.sas.actionprovider.BaseActionProvider

getActionOrderList, getDefaultAction, getLocale, getName, listActionTypes, listAreaTypes, listDefaultActions, newActionInstance, setAction, setActionOrderList, setLocale, setName

Field Detail

ALL_VIEWERS

public static final java.lang.String ALL_VIEWERS

Key used when flushing references to all viewers from this HttpActionProvider.

See Also:

flush, Constant Field Values

CMDID

public static final java.lang.String CMDID

Key used with url template substitution when mapping to the unique identifier of a command instance stored on this HttpActionProvider.

See Also:

Constant Field Values

APNAME

public static final java.lang.String APNAME

Key used with url template substitution when mapping to the name of this HttpActionProvider.

See Also:

Constant Field Values

DYNAMICATTRS

public static final java.lang.String DYNAMICATTRS

Key used with url template substitution when mapping to the url query string that gets generated from the attributes of an HttpAction.

See Also:

HttpAction, Constant Field Values

PARMPREFIX

public static final java.lang.String PARMPREFIX

Key used when mapping to the parameterPrefix attribute of this HttpActionProvider.

See Also:

getParameterPrefix(), Constant Field Values

BASEURL

public static final java.lang.String BASEURL

Key used with url template substitution when mapping to the base of the url string that gets generated from the attributes of an HttpAction.

See Also:

HttpAction, Constant Field Values

AJAX_CONTROLLER_URL

public static final java.lang.String AJAX_CONTROLLER_URL

Key used with url template substitution when mapping to the ajax controller url specified on the viewer component.

See Also:

com.sas.servlet.tbeans.AjaxURLInterface, Constant Field Values

VIEWERID

public static final java.lang.String VIEWERID

Key used with url template substitution when mapping to the id of viewer component.

See Also:

Constant Field Values

REFRESHVIEWERID

public static final java.lang.String REFRESHVIEWERID

Key used with url template substitution when mapping to the id of the viewer that will be refreshed when after the action is performed.

See Also:

Constant Field Values

REFERRINGURI

public static final java.lang.String REFERRINGURI

Key used with url template substitution when mapping to the original URI of the viewer.

See Also:

Constant Field Values

QUERYSTRING

public static final java.lang.String QUERYSTRING

Key used with url template substitution when mapping to the Action Provider related parameters associated with an Action.

See Also:

Constant Field Values

CONTEXTPATH

public static final java.lang.String CONTEXTPATH

Key used with url template substitution when mapping to the request context path.

See Also:

Constant Field Values

REFERRING_URI_PARAMETER

public static final java.lang.String REFERRING_URI_PARAMETER

Key used to name the request parameter that holds the uri of the referring request.

See Also:

Constant Field Values

VIEWER_ID_PARAMETER

public static final java.lang.String VIEWER_ID_PARAMETER

Key used to name the request parameter that holds the id of the viewer component that queries for an Action.

See Also:

Constant Field Values

REFRESH_VIEWER_ID_PARAMETER

public static final java.lang.String REFRESH_VIEWER_ID_PARAMETER

Key used to name the request parameter that holds the id of the viewer component that queries for an Action.

See Also:

Constant Field Values

Constructor Detail

HttpActionProvider

public HttpActionProvider()

Default constructor

Throws:

java.lang.IllegalStateException - if HttpSupportClasses.properties file can not be loaded.

Method Detail

getParameterPrefix

public java.lang.String getParameterPrefix()

Returns the prefix that is prepended to the names of all non-external request parameters.

The prefix is used by the HttpActionProvider, during its command execution phase, to assist in identifying which parameters on the request should be applied as command attributes.

This method never returns null. The default value is the name of this ActionProvider followed by an underscore character.

Returns:

the prefix that is prepended to the names of all non-external request parameters.

See Also:

setParameterPrefix(java.lang.String)

setParameterPrefix

public void setParameterPrefix(java.lang.String parameterPrefix)

Sets the prefix that is prepended to the names of all non-external request parameters.

The prefix is used by the HttpActionProvider, during its command execution phase, to assist in identifying which parameters on the request should be applied as command attributes.

Parameters:

parameterPrefix - the prefix that is prepended to the names of all request parameters.

See Also:

getParameterPrefix()

setControllerURL

public void setControllerURL(java.lang.String controllerURL)

Sets the url of a central controller or generic handler.

For use when integrating the action provider into a web application that uses a controller or handler to process requests.

The controllerURL influences the base of the URL that is generated for every Action returned by the HttpActionProvider unless overridden on a per-Action or per-Viewer basis.

The precedence of all factors influencing URL generation, in decreasing order, follows:

1. The Action's URLBase attribute
2. The Action's URLTemplate attribute
3. The URLTemplate attribute of any viewer that implements the URLTemplateViewInterface
4. The HttpActionProvider's controllerURL attribute
5. The URI of the viewer's current request

Parameters:

controllerURL - the url of the controller which should be the href on all actions returned by this action provider unless overriden on a per-Action or per-Viewer basis.

See Also:

getControllerURL(), HttpAction.setURLBase(java.lang.String), HttpAction.setURLTemplate(com.sas.util.SimpleTemplate), URLTemplateViewInterface.setURLTemplate(com.sas.util.SimpleTemplate), HttpActionProviderViewInterface.setRequest(javax.servlet.http.HttpServletRequest)

getControllerURL

public java.lang.String getControllerURL()

Returns the url of a central controller or generic handler.

Returns:

the url of the controller.

See Also:

setControllerURL(java.lang.String)

setUseReferringURIParameter

public void setUseReferringURIParameter(boolean useReferringURIParameter)

Sets the boolean indicating whether a REFERRING_URI_PARAMETER should be set on all Actions returned by this action provider.

The value of this attribute will be the value obtained via:

request.getRequestURI()

where request is the HttpServletRequest of the viewer calling getActions().

Parameters:

useReferringURIParameter - the boolean indicating whether REFERRING_URI_PARAMETER should be set on all actions returned by this action provider.

See Also:

HttpActionProviderViewInterface.getRequest(), HttpServletRequest, getUseReferringURIParameter()

getUseReferringURIParameter

public boolean getUseReferringURIParameter()

Return the boolean indicating whether a REFERRING_URI_PARAMETER is set on all actions returned by this action provider.

Returns:

the the boolean indicating whether REFERRING_URI_PARAMETER attribute is set on all actions returned by this action provider. #setUseReferringURIParameter

addExternalRequestParameter

public void addExternalRequestParameter(HttpActionProviderViewInterface viewer,
                                        java.lang.String parameterName,
                                        java.lang.String parameterValue)

Adds a key/value pair of request parameters to be included on all Actions returned by this ActionProvider.

Parameters:

viewer - the instance of the viewer component whose actions should include the external parameters. If null, the external parameters are included on actions returned to all viewers. A viewer-specific parameter value will override a non viewer-specific parameter whenever they match.

parameterName - the name of the request parameter

parameterValue - the request parameter's value

See Also:

getExternalRequestParameters(), getExternalRequestParameters(HttpActionProviderViewInterface)

addExternalRequestParameters

public void addExternalRequestParameters(HttpActionProviderViewInterface viewer,
                                         java.util.Map externalParameters)

Adds multiple key/value pairs of request parameters to be included on the actions returned by this action provider.

Parameters:

viewer - the instance of the viewer component whose actions should include the external parameters. If null, the external parameters are included on actions returned to all viewers. A viewer-specific parameter value will override a non viewer-specific parameter whenever they match.

externalParameters - a map of key/value pairs where the key is the attribute name and the value is the attribute value.

See Also:

getExternalRequestParameters(), getExternalRequestParameters(HttpActionProviderViewInterface)

getExternalRequestParameters

public java.util.Map getExternalRequestParameters(HttpActionProviderViewInterface viewer)

Returns a map of all the key/value pairs to be included on every action returned by this action provider for a specific viewer.

Parameters:

viewer - The viewer to which the external parameters apply.

Returns:

a map of all the key/value pairs to be included on every action returned by this action provider.

See Also:

addExternalRequestParameter(com.sas.actionprovider.HttpActionProviderViewInterface, java.lang.String, java.lang.String), addExternalRequestParameters(com.sas.actionprovider.HttpActionProviderViewInterface, java.util.Map)

getExternalRequestParameters

public java.util.Map getExternalRequestParameters()

Returns a map of all the key/value pairs to be included on every action returned by this action provider.

Returns:

a map of all the key/value pairs to be included on every action returned by this action provider.

See Also:

addExternalRequestParameter(com.sas.actionprovider.HttpActionProviderViewInterface, java.lang.String, java.lang.String), addExternalRequestParameters(com.sas.actionprovider.HttpActionProviderViewInterface, java.util.Map)

getExecutableCommand

public DynamicAttributeCommandInterface getExecutableCommand(javax.servlet.http.HttpServletRequest request)

Returns an executable copy of the command object referred to by the CMDID parm on the request object and that is stored on the ActionProvider.

All dynamic attributes are applied to the command by this method.

Parameters:

request - HttpServletRequest object whose CMDID parm tells the ActionProvider which command to get.

Returns:

the command that is identified by the CMDID parm on the request and that is stored on the ActionProvider.

Returns null if CMDID not found on request or if CMDID doesnt reference a stored command.

Throws:

java.lang.IllegalArgumentException - if request argument is null.

java.lang.IllegalStateException - if stored command found but an executable version of the command could not be obtained.

See Also:

CMDID

applyCommandAttributes

public void applyCommandAttributes(javax.servlet.http.HttpServletRequest request,
                                   DynamicAttributeCommandInterface command)

Applies command attributes that are on the request or are stored on this ActionProvider.

Parameters:

request - HttpServletRequest object whose CMDID parameter identifies the set of stored attribute values on the HttpActionProvider.

command - The command to which the attribute values should be applied.

Throws:

java.lang.IllegalArgumentException - if either argument is null.

See Also:

CMDID

getStoredCommandAttributes

public java.util.Map getStoredCommandAttributes(javax.servlet.http.HttpServletRequest request)

Returns a copy of the Map of stored attributes that is associated with the CMDID parameter on the request object.

Parameters:

request - request object whose CMDID parm identifies which stored property map to return.

Returns:

the Map of stored properties where the map keys are property name's and the map's values are property values.

Throws:

java.lang.IllegalArgumentException - if request argument is null.

See Also:

CMDID, getRequestCommandAttributes(javax.servlet.http.HttpServletRequest)

getRequestCommandAttributes

public java.util.Map getRequestCommandAttributes(javax.servlet.http.HttpServletRequest request)

Returns a Map of all the request parameters that match properties on the command.

Only request parameters having names beginning with the ActionProvider's parameterPrefix can be matched to a command attribute.

The method also transforms request values from String Objects to the appropriate Object types on the command.

Returns an empty Map for any of thhe following reasons:

• No CMDID parameter on request.
• No command currently referenced by the CMDID parameter on the request.
• Introspection on the store command fails.
• No parameters on the request match any of the command attributes.
• No parameters values could be transformed to the corresponding type on the command.

Parameters:

request - request object whose CMDID parm tells the HttpActionProvider which command's properties to look for on the request.

Returns:

the Map of request properties where the map keys are property name's and the map's values are transformed property values.

See Also:

CMDID, getStoredCommandAttributes(javax.servlet.http.HttpServletRequest), getParameterPrefix()

flush

public void flush(java.lang.Object viewer)

Flushes all internal objects held for the specified viewer object.

If viewer object is a BaseCompositeTransformation, this method is then called on each of the composite's components.

Parameters:

viewer - the object for which all internal objects should be flushed.

executeCommand

public void executeCommand(DynamicAttributeCommandInterface command,
                           javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response,
                           java.lang.Object obj)
                    throws java.io.IOException

Executes the command.

Additionally, this method ensures that any pending PendingCommandInterface commands from previous executions are cancelled if this command object is different.

Also, if the command implements the ContentsChangedInterface, this method fires ActionProviderEvents to each of this ActionProvider's listeners.

Typically, the other executeCommand() method that does not take a command Object as an arg should be used. However, if there is a need to acquire the command before it is executed, you may use this method in conjunction with the getExecutableCommand() method.

Parameters:

command - The command to be executed.

request - HttpServletRequest object whose CMDID parameter references the command and stored property entry to be executed.

response - The command object to be executed.

obj - The output stream for writing the results of this command.

Throws:

java.lang.IllegalArgumentException - if command argument is null.

java.io.IOException

See Also:

getExecutableCommand(javax.servlet.http.HttpServletRequest), CMDID, PendingCommandInterface, ContentsChangedInterface, executeCommand(HttpServletRequest, HttpServletResponse, Object), getExecutableCommand(javax.servlet.http.HttpServletRequest)

executeCommand

public DynamicAttributeCommandInterface executeCommand(javax.servlet.http.HttpServletRequest request,
                                                       javax.servlet.http.HttpServletResponse response,
                                                       java.lang.Object obj)
                                                throws java.io.IOException

Executes the command associated with the CMDID parameter on the HttpServletRequest.

All dynamic command attributes from the request or that are stored on this ActionProvider are applied to the command prior to its execution.

The request and response arguments passed to this method are also set on the command prior to its execution.

This method ensures that any pending PendingCommandInterface commands from previous executions are cancelled if this command object is different.

Also, if the command implements the ContentsChangedInterface, this method fires ActionProviderEvents to each of this ActionProvider's listeners.

Typically, the other executeCommand() method that does not take a command Object as an arg should be used. However, if there is a need to acquire the command before it is executed, you may use this method in conjunction with the getExecutableCommand() method.

Parameters:

request - HttpServletRequest object whose CMDID parameter references the command and its stored attributes.

response - The HttpServletResponse object.

obj - The output stream for writing the results of this command.

Throws:

java.lang.IllegalArgumentException - if request argument is null.

java.lang.IllegalStateException - if stored command found but an executable version of the command could not be obtained.

java.io.IOException

See Also:

CMDID, PendingCommandInterface, ContentsChangedInterface, executeCommand(HttpServletRequest, HttpServletResponse, Object), getExecutableCommand(javax.servlet.http.HttpServletRequest)

storeCommand

public java.lang.String storeCommand(DynamicAttributeCommandInterface command,
                                     java.lang.Object viewer,
                                     java.util.Map storedProperties)

Stores the command on this HttpActionProvider.

Returns a String cmdId that is the unique lookup reference to the stored command and its map of stored command attributes.

Parameters:

command - The command object to be stored.

viewer - A viewer object associated with the command that must also be stored.

storedProperties - The Map of properties and values associated with the command that also must be stored.

Returns:

A String cmdId that references all the stored command information.

Throws:

java.lang.IllegalArgumentException - if command or viewer are null.

fireContentsChanged

public void fireContentsChanged(ActionProviderEvent event)

Send a ActionProviderEvent event to all the ContentsChangedListener objects in the listener list.

The event is sent only to each item which is in the list at the time this method is called, even if adds or removes are performed after the this method has started.

Also sends the event, which extends PropertyChangeEvent, to all registered property change listeners.

Parameters:

event - the event to send