Provides the integrated set of classes that comprise the ActionProvider Framework (APF).


OVERVIEW

    The APF is a framework from which both Swing and JSP Viewer Components acquire their Actions. See the CURRENT APF VIEWERS section below for a listing of viewers that currently use the APF.

    The main purpose of the framework is to give users the ability to customize the functionality and appearance of these Actions. However, before attempting to exploit these features of the APF, a basic understanding of its primary elements is essential.


PRIMARY TYPES OF CLASSES IN THE APF

Actions
Primary Classes:

These are objects that encapsulate everything needed to:

  1. Perform a particular type of operation for the View Component.

  2. Represent the Action visually.

** Typically, a Command object associated with the Action contains the logic for actually performing the operation. Within the APF, all commands are required to be implementations of {@link com.sas.commands.DynamicAttributeCommandInterface}. The {@link com.sas.commands.BaseCommand} class implements that interface and is the base class for all default commands.

Viewer Components
Primary Classes:

These objects query an ActionProvider, via its {@link com.sas.actionprovider.BaseActionProvider#getActions getActions()} method, for each renderable portion of their view.

ActionProviders
Primary Classes:

These objects delegate viewer queries for actions and all user interactions to the appropriate type of APF support class. There are different support classes for different viewer-type/model-type combinations. See {@link com.sas.actionprovider.support.ActionProviderSupportTypes} for an overview of the the default support classes.

Support classes
Primary Classes:

Generally, these objects are responsible for the following:

  1. Define the general areaTypes in which Actions may be registered. For example, a table support class may define a COLUMN_HEADER_AREA and a DATA_CELL_AREA.

  2. Define the default actionTypes and map each type to an Action instance that it creates and registers to an areaType.

  3. Provide dynamic attribute values for Actions during a viewer's getActions() query. These are values that typically vary depending on the specific area for which the viewer is querying. For example, some attributes of the Actions in a table's column header cell would likely have different values.

    Most efforts of users to override or add their own custom actions for a particular Viewer Component should start with identifying the support class for that viewer. See the CURRENT APF VIEWERS section below for the default mappings between supportType keys and support classes. Each support class documents its default actionTypes and the areaTypes to which they are registered.

    Neither viewers or users interact directly with instances of a support class. Instead, both interact with an ActionProvider which delegates method calls to a support class based on a specified supportType key.


OPERATIONAL FLOW OF THE APF

There are two primary operational phases of the APF:

The Action acquisition phase is similar in the Swing and JSP/Servlet environments.

  1. A Viewer Component makes a query for Actions to its ActionProvider via a {@link com.sas.actionprovider.BaseActionProvider#getActions getActions()} call. There may be multiple calls to this method; One for each specific area within a general areaType. For example, a TableView component does a different query for each of its column headers within the general COLUMN_HEADER_AREA. JSP/Servlet Components have to make as many queries as there are specific areas during each rendering of the view. Swing Components can query for Actions on just an as-needed basis; When a users clicks an area to bring up a pop menu of Action choices for example. The query always includes the following:

    • The instance of the Viewer Component making the query.
    • The supportType key. See {@link com.sas.actionprovider.support.ActionProviderSupportTypes}
    • The areaType key. e.g. {@link com.sas.actionprovider.support.tableview.BaseTableViewSupport#COLUMN_HEADER_AREA} for a TableView

    The other parts required on the query depend on the particular support class. Typically, they include:

    • An instance of the model to which the Viewer Component is attached.
    • Indexes or other more complex objects that identify the specific area for which the query is being made. For example, a column's model index or OLAP TupleElement.

  2. The ActionProvider delegates the {@link com.sas.actionprovider.BaseActionProvider#getActions getActions()} call to the appropriate support class based on the specified supportType key.

  3. The support class identifies all the actionTypes that are registered for the specified areaType and does the following for each of the Actions to which they are associated:

    • Determines if the Action should be returned with the query according to its presence on the ActionOrderList that is in effect and the visibility status on the Viewer Component. See {@link com.sas.actionprovider.BaseActionProvider#setActionOrderList setActionOrderList()} on the base ActionProvider class and {@link com.sas.actionprovider.ActionProviderViewInterface#setActionVisible setActionVisible} on the Viewer component.
    • Determine if the Action is disabled and, if so, should it be returned in a disabled state. See {@link com.sas.actionprovider.support.BaseActionProviderSupport#getActionStatus getActionStatus()} on the base support class and {@link com.sas.actionprovider.BaseAction#setReturnStatus setReturnStatus()} on the base Action class.
    • If it is determined that Action should be returned for the query, the support class makes a copy of the registered Action instance and applies all the dynamic values to it. See the {@link com.sas.actionprovider.BaseAction#DYNAMIC DYNAMIC} supplemental attribute property defined on the base Action class.
    • The support class returns all the Actions that satisfy the query in the form of an {@link com.sas.actionprovider.ActionList} whose structure is defined by the {@link com.sas.actionprovider.ActionOrderList} that is in effect on the support class.

  4. In the JSP/Servlet environment, Actions can not persist after they are acquired and their html representations have been returned to the client. Therefore, the {@link com.sas.actionprovider.HttpActionProvider} stores command instances and, possibly, certain dynamic Action attributes so that the command may be executed later during a new request from the client. The HttpActionProvider assigns a unique {@link com.sas.actionprovider.HttpActionProvider#CMDID} identifier for each of its stored commands.



The Action / Command execution phase is different in the Swing and JSP/Servlet environments.

    The Swing execution phase starts when the SwingAction's {@link com.sas.actionprovider.BaseAction#actionPerformed actionPeformed()} method is called by the Viewer Component itself or some Action handler like {@link javax.swing.JPopupMenu}. This base implementation of this method does just the following:

  1. For every attribute on the command, the method looks for an attribute with the same name on the SwingAction and applies the Action's value to the command.
  2. The command's {@link com.sas.commands.BaseCommand#execute execute()} method is called.
  3. If the executed command implements the {@link com.sas.commands.ContentsChangedInterface} and the {@link com.sas.commands.ContentsChangedInterface#isContentsChanged isContentsChanged()} method returns true, then the SwingActionProvider that generated the Action is told to fire an {@link com.sas.actionprovider.ActionProviderEvent} to all of its listeners.

    The JSP/Servlet execution phases starts when the HttpActionProvider's {@link com.sas.actionprovider.HttpActionProvider#executeCommand(HttpServletRequest, HttpServletResponse, Object) executeCommand()} method is called. This method does the following:

  1. Lookup the stored command to be executed using the {@link com.sas.actionprovider.HttpActionProvider#CMDID} identifier that is passed as a request parameter.
  2. For every attribute on the command, the method looks for an attribute with the same name, except prepended with the HttpActionProvider's {@link com.sas.actionprovider.HttpActionProvider#getParameterPrefix parameterPrefix}, on the request object. If not found on the request, the method looks for the attribute with the same name in the set of stored attributes for the command.
  3. If match for command attribute found, the attribute value is transformed, if possible, to the appropriate Object type and then set on the command.
  4. The command's {@link com.sas.commands.DynamicAttributeCommandInterface#execute execute()} method is called.
  5. If the executed command implements the {@link com.sas.commands.ContentsChangedInterface} and the {@link com.sas.commands.ContentsChangedInterface#isContentsChanged isContentsChanged()} method returns true, then the HttpActionProvider fires an {@link com.sas.actionprovider.ActionProviderEvent} to all of its listeners.

CURRENT APF VIEWERS

    The following is a list of Viewer Components that use the APF including their default APF support class and the supportKey.

Viewer Support Key Support Class
{@link com.sas.swing.visuals.tableview.TableView Swing TableView} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#TABLEVIEW_SUPPORT TABLEVIEW_SUPPORT} {@link com.sas.actionprovider.support.tableview.SwingTableViewSupport}
{@link com.sas.swing.visuals.olaptableview.OLAPTableView Swing OLAPTableView} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_TABLEVIEW_SUPPORT OLAP_TABLEVIEW_SUPPORT} {@link com.sas.actionprovider.support.olaptableview.SwingOLAPTableViewSupport}
{@link com.sas.swing.visuals.olaptableview.OLAPDrillState Swing OLAPDrillState} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_DRILLSTATE_SUPPORT OLAP_DRILLSTATE_SUPPORT} {@link com.sas.actionprovider.support.olaptableview.SwingOLAPDrillStateSupport}
{@link com.sas.swing.visuals.remotefileselector.IFileServiceSelectorPanel Swing IFileServiceSelectorPanel} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_IFILE_SERVICE_SUPPORT REMOTE_IFILE_SERVICE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.SwingIFileServiceSupport}
{@link com.sas.swing.visuals.remotefileselector.InformationServicesSelectorPanel Swing InformationServicesSelectorPanel} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_INFO_SERVICE_SUPPORT REMOTE_INFO_SERVICE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.SwingInformationServiceSupport}
*{@link com.sas.swing.visuals.remotefileselector.RemoteFileSearchComponent Swing RemoteFileSearchComponent} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_IFILE_SERVICE_SUPPORT REMOTE_IFILE_SERVICE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.SwingInformationServiceSupport}
*{@link com.sas.swing.visuals.remotefileselector.RemoteFileSearchComponent Swing RemoteFileSearchComponent} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_INFO_SERVICE_SUPPORT REMOTE_INFO_SERVICE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.SwingInformationServiceSupport}
{@link com.sas.servlet.tbeans.tableview.html.TableView JSP/Servlet TableView} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#TABLEVIEW_SUPPORT TABLEVIEW_SUPPORT} {@link com.sas.actionprovider.support.tableview.HttpTableViewSupport}
{@link com.sas.servlet.tbeans.olaptableview.html.OLAPTableView JSP/Servlet OLAPTableView} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_TABLEVIEW_SUPPORT OLAP_TABLEVIEW_SUPPORT} {@link com.sas.actionprovider.support.olaptableview.HttpOLAPTableViewSupport}
{@link com.sas.servlet.tbeans.dataselectors.html.RelationalMenuBar JSP/Servlet RelationalMenuBar} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#RELATIONAL_MENUBAR_SUPPORT RELATIONAL_MENUBAR_SUPPORT} {@link com.sas.actionprovider.support.dataselectors.HttpRelationalMenuBarSupport}
{@link com.sas.servlet.tbeans.dataselectors.html.OLAPMenuBar JSP/Servlet OLAPMenuBar} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_MENUBAR_SUPPORT OLAP_MENUBAR_SUPPORT} {@link com.sas.actionprovider.support.dataselectors.HttpMenuBarSupport}
**{@link com.sas.servlet.tbeans.navigationbar.html.NavigationBarRowScrollingElement JSP/Servlet NavigationBarRowScrollingElement} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#NAVIGATIONBAR_SUPPORT NAVIGATIONBAR_SUPPORT} {@link com.sas.actionprovider.support.HttpNavigationBarSupport}
**{@link com.sas.servlet.tbeans.navigationbar.html.NavigationBarRowScrollingElement JSP/Servlet NavigationBarColumnScrollingElement} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#NAVIGATIONBAR_SUPPORT NAVIGATIONBAR_SUPPORT} {@link com.sas.actionprovider.support.HttpNavigationBarSupport}
{@link com.sas.servlet.tbeans.html.Label JSP/Servlet Label} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#CUSTOM_SUPPORT CUSTOM_SUPPORT} {@link com.sas.actionprovider.support.HttpCustomSupport}
***{@link com.sas.servlet.tbeans.remotefileselector.html.RemoteFileSearch JSP/Servlet RemoteFileSearch} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.HttpRemoteFileSelectorCompositeSupport}
***{@link com.sas.servlet.tbeans.remotefileselector.html.RemoteFileToolBar JSP/Servlet RemoteFileToolBar} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.HttpRemoteFileSelectorCompositeSupport}
***{@link com.sas.servlet.tbeans.tableview.html.TableView JSP/Servlet RemoteFileSelector TableView} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT REMOTE_FILE_SELECTOR_COMPOSITE_SUPPORT} {@link com.sas.actionprovider.support.remotefileselector.HttpRemoteFileSelectorCompositeSupport}
{@link com.sas.servlet.tbeans.olaptableview.html.OLAPDrillState JSP/Servlet OLAPDrillState} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_DRILLSTATE_SUPPORT OLAP_DRILLSTATE_SUPPORT} {@link com.sas.actionprovider.support.olaptableview.HttpOLAPDrillStateSupport}
{@link com.sas.servlet.tbeans.graphics.html.BarChart JSP/Servlet BarChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.BarLineChart JSP/Servlet BarLineChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.LineChart JSP/Servlet LineChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.LinePlot JSP/Servlet LinePlot} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.PieChart JSP/Servlet PieChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.ScatterPlot JSP/Servlet ScatterPlot} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.BarChartComposite JSP/Servlet BarChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.BarLineChartComposite JSP/Servlet BarLineChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.LineChartComposite JSP/Servlet LineChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.LinePlotComposite JSP/Servlet LinePlotComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.PieChartComposite JSP/Servlet PieChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.graphics.html.ScatterPlotComposite JSP/Servlet ScatterPlotComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#GRAPH_SUPPORT GRAPH_SUPPORT} {@link com.sas.actionprovider.support.graphics.HttpGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPBarChart JSP/Servlet OLAPBarChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPBarLineChart JSP/Servlet OLAPBarLineChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPLineChart JSP/Servlet OLAPLineChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPLinePlot JSP/Servlet OLAPLinePlot} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPPieChart JSP/Servlet OLAPPieChart} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPScatterPlot JSP/Servlet OLAPScatterPlot} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPBarChartComposite JSP/Servlet OLAPBarChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPBarLineChartComposite JSP/Servlet OLAPBarLineChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPLineChartComposite JSP/Servlet OLAPLineChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPLinePlotComposite JSP/Servlet OLAPLinePlotComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPPieChartComposite JSP/Servlet OLAPPieChartComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}
{@link com.sas.servlet.tbeans.olapgraphics.html.OLAPScatterPlotComposite JSP/Servlet OLAPScatterPlotComposite} {@link com.sas.actionprovider.support.ActionProviderSupportTypes#OLAP_GRAPH_SUPPORT OLAP_GRAPH_SUPPORT} {@link com.sas.actionprovider.support.olapgraphics.HttpOLAPGraphSupport}

*Note: The support class used by the Swing RemoteFileSearchComponent is dependent on the type of RemoteFileSelector it is being used within. If used within the {@link com.sas.swing.visuals.remotefileselector.InformationServicesSearchPanel} then it uses the support class mapped to {@link com.sas.actionprovider.support.ActionProviderSupportTypes#REMOTE_INFO_SERVICE_SUPPORT REMOTE_INFO_SERVICE_SUPPORT}.

**Note: The NavigationBarRowScrollingElement and NavigationBarColumnScrollingElement are used within the {@link com.sas.servlet.tbeans.navigationbar.html.TableRowNavigationBar} and {@link com.sas.servlet.tbeans.navigationbar.html.TableColumnNavigationBar}, respectively.

***Note: All three components are used within the {@link com.sas.servlet.tbeans.remotefileselector.html.InformationServicesSelector} and the {@link com.sas.servlet.tbeans.remotefileselector.html.RemoteFileSelector} components.


For More Information

Examples demonstrating how to use the ActionProvider Framework may be found on the ActionProvider Framework Examples Site.

** You will initially see a subset of examples relating to this framework. You can search for other types of examples as needed.

Also, 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/.