2 Introducing Analytic Workspace Manager Plug-ins

Enabling Analytic Workspace Manager Plug-ins

Analytic Workspace Manager has a configuration option that specifies whether it uses plug-ins. To enable plug-ins, from the Analytic Workspace Manager Tools menu, select Configuration, as shown in Figure 2-1. In the Configuration dialog box, select Enable Plugins and specify the directory that contains your plug-ins, as shown in Figure 2-2. Click OK and then exit and restart Analytic Workspace Manager.

Figure 2-1 Configuration Item on the Tools Menu

Description of "Figure 2-1 Configuration Item on the Tools Menu"

Figure 2-2 shows the Configuration dialog box with Enable plugins selected and with plugin as the value for Plugin directory. The value should include the full path to the plug-in directory unless the directory is a subdirectory of the Oracle_home/olap/awm directory, which is the case for the plugin directory shown in the figure.

Figure 2-2 Configuration Dialog Box with Enable Plugins Selected

Description of "Figure 2-2 Configuration Dialog Box with Enable Plugins Selected"

How Analytic Workspace Manager Calls a Plug-in

If Analytic Workspace Manager has plug-ins enabled, then on startup Analytic Workspace Manager dynamically loads Java code from JAR files located in the plug-ins directory. After loading the contents of the JAR files, Analytic Workspace Manager looks for classes that implement the AWMPlugin, ViewerPlugin, or EditorPlugin interfaces. It also looks for aw.xml, cube.xml, dimension.xml, and schema.xml files to add objects to the navigation tree.

When Analytic Workspace Manager calls most methods of a plug-in, it passes the method a java.sql.Connection object as the conn parameter. The Connection represents the current connection to the Oracle Database instance.

Analytic Workspace Manager does not pass any user identification or password to the plug-in. It only passes the connection object. An Analytic Workspace Manager plug-in does not allow you to do anything that you cannot do by writing a standalone Java program. For information on the parameters that Analytic Workspace Manager passes to the methods of plug-ins, see "Describing the AWMPlugin Interface" and "Describing the ViewerPlugin and EditorPlugin Interfaces".

Calling an AWMPlugin

When a user right-clicks an object in the Analytic Workspace Manager navigation tree, a menu appears that presents the actions available for the object. The menu also displays options supplied by the AWMPlugin plug-ins that apply to the object. An AWMPlugin uses the isSupported method to indicate whether it applies to an object in the tree. Because Analytic Workspace Manager calls the isSupported method of each plug-in whenever the user right-clicks a navigation tree object, an isSupported method should return quickly.

The menu displays the text returned by the getMenu method of the plug-in. Figure 2-3 shows the menu that Analytic Workspace Manager displays when a user right-clicks a calculated measure in the tree. The menu includes the ViewXMLPlugin example plug-in. For the code of the plug-in example, see Example 3-1.

Figure 2-3 Right-click Menu of the Navigation Tree for a Calculated Measure

Description of "Figure 2-3 Right-click Menu of the Navigation Tree for a Calculated Measure"

If the user selects the plug-in, then Analytic Workspace Manager calls the handle method of the plug-in. The handle method specifies the actions that the plug-in performs. The refreshTree method of the plug-in indicates whether Analytic Workspace Manager refreshes the navigation tree to include any new objects created by the plug-in or to remove objects deleted by the plug-in.

Values for the type and obj Parameters

For the type parameter of the methods of an AWMPlugin implementation, Analytic Workspace Manager passes to the plug-in a label that identifies the type of the navigation tree object for which the plug-in is invoked. For the obj parameter of the methods, Analytic Workspace Manager passes an Object, which is a java.lang.String or an OLAP metadata object.

A plug-in can use the type value to distinguish between the navigation tree objects that are associated with the same metadata object. For example, for all of the folder objects in a Dimensions folder, such as Levels and Hierarchies, Analytic Workspace Manager passes as the obj parameter the same MdmPrimaryDimension object, but it passes a different type label for each folder object.

Custom objects that you add with an XML document appear in the navigation tree at the level specified by the XML document. For example, a top-level <AWMNode> in a dimension.xml document appears in the Dimensions folder of an analytic workspace. For an AWMPlugin implementation specified by an <AWMNode> element, the type parameter value has the prefix AWMTree_ followed by the value of the name attribute of the parent <AWMNode>. The obj parameter value is the run-time value of the type attribute of the <AWMNode>.

Table 2-1 shows the type parameter values and obj parameter objects that Analytic Workspace Manager passes to the plug-in for the selected navigation tree object. The indentation of objects in the Navigation Tree Object column indicates the hierarchy of the tree. Text in italics indicates a variable object name. The obj parameter objects are String objects or OLAP metadata objects. The AW object is an oracle.olapi.metadata.deployment.AW object. The other metadata objects, such as MdmStandardDimension and MdmCube, are classes in the oracle.olapi.metadata.mdm package. The Reports object and all of the objects under it have the same type.

Elements in the params Map for an AWMPlugin

The params Map contains information about the navigation tree object that is currently selected. Table 2-2, "Keys and Values of the params Map for a Non-custom Object" and Table 2-3, "Keys and Values of the params Map for a Custom Object" contain descriptions of the keys and values of the elements of the Map for an AWMPlugin The keys are String objects.

The params Map for the Database folder does not have a DATASOURCE, DATAPROVIDER, or GETDATAPROVIDER key. The params Map objects for the higher level navigation tree objects, those above the individual analytic workspaces, have a null value for the DATAPROVIDER key until the user selects a tree object that requires OLAP metadata. Other than for those exceptions, the params Map for a navigation tree object has the keys and values listed in the tables.

Example params Map Elements for an AWMPlugin

Examples of the keys and values of a params Map for a custom object are in Table 2-5 and in Table 2-6. All of the values are String objects except those for the DATAPROVIDER and DATASOURCE keys.

Table 2-6 has the elements of the params Map that Analytic Workspace Manager passes to the methods of DeleteDimPlugin when the user right-clicks the CUSTOMER dimension in the MyDims folder, as shown in Figure 3-2. The MyDims folder is created by the aw.xml document in Example 3-7.

The figure shows the menu that DeleteDimPlugin displays. The property inspector in the figure has the output of DimEditorPlugin, because that plug-in is also activated when the user selects a dimension in the MyDims folder.

An example of getting a value from the params Map is the following line from the isSupported method in the DeleteDimPlugin class in Example 3-2.

Object nodeType = params.get("TYPE");

Table 2-6 has the elements of the Map that is the value of the BIND_MAP key in the params Map. An example of getting a value from the BIND_MAP Map is the following lines from the handle method in the DeleteDimPlugin class in Example 3-2.

Map bindMap = (Map)params.get("BIND_MAP");
...
String owner = (String)bindMap.get("owner");

Describing the ViewerPlugin Interface

The following is the oracle.olap.awm.plugin.ViewerPlugin interface.

package oracle.olap.awm.plugin

import java.sql.Connection;
import java.util.Map;
import javax.swing.JPanel;

public interface ViewerPlugin
{
  public boolean isViewerForType(Connection conn, String name) 
    throws Exception;

  public JPanel getPanel(Connection conn, String name, Map params)
    throws Exception;

  public void cleanup(String name);
}

When the Analytic Workspace Manager user selects the navigation tree object that is associated with the ViewerPlugin, Analytic Workspace Manager calls the methods of a ViewerPlugin in the sequence illustrated in Figure 2-5.

Figure 2-5 Sequence of Calls to a ViewerPlugin

Description of "Figure 2-5 Sequence of Calls to a ViewerPlugin"

Analytic Workspace Manager first calls the isViewerForType method and passes it the following parameters:

• conn, which is a java.sql.Connection object that represents the current connection to the Oracle Database instance.

• name, which is a String that contains the name of the <AWMNode> that is the parent of the <AWMNode> that has the viewClass attribute.

If the plug-in returns true, Analytic Workspace Manager calls the getPanel method and passes it the same conn and name parameters plus the following parameter.

• params, which is a java.util.Map object that contains information about the currently selected navigation tree object. The information includes the run-time values for attributes of the <AWMNode> element that has the viewClass attribute and from the parent <AWMNode>. The plug-in can use this information in specifying data to display or to retrieve from the database. The keys and values of the Map are described in Table 2-7. For a description of the Map keys and values, see "Elements in the params Map for a ViewerPlugin or EditorPlugin".

When the user selects a different navigation tree object, Analytic Workspace Manager calls the cleanup method of the plug-in. It passes the method the same name parameter. In this method you can perform any cleanup that your plug-in requires.

Describing the EditorPlugin Interface

The EditorPlugin interface extends the ViewerPlugin interface. The following is the oracle.olap.awm.plugin.EditorPlugin interface.

package oracle.olap.awm.plugin

import java.awt.Component;
import java.sql.Connection;
import java.util.Map;

public interface EditorPlugin extends ViewerPlugin
{
  public void setValueChanged(Connection conn, String name, Map params,
    PanelChanged parent);

  public boolean validate(Connection conn, Component parent, String name, 
    Map params) throws Exception;

  public boolean save(Connection conn, Component parent, String name,
    Map params) throws Exception;

  public void revert(Connection conn, Component parent, String name, 
    Map params) throws Exception;

  public void showHelp(Connection conn, Component parent, String name,
    Map params) throws Exception;
}

For an EditorPlugin, Analytic Workspace Manager initially calls the isViewerForType, setValueChanged, and getPanel methods, as shown in Figure 2-6, "Sequence of Calls to an EditorPlugin". For an example of the display of an EditorPlugin, see Figure 3-11.

If the user makes a change in the property inspector, then the Apply and Revert buttons become active. If the user clicks Apply, then Analytic Workspace Manager calls the validate method of the EditorPlugin. If the value is valid, then Analytic Workspace Manager calls the save method. If the user clicks Revert, then Analytic Workspace Manager calls revert. If the user clicks the Help button, then Analytic Workspace Manager calls showHelp.

All of the methods of an EditorPlugin have the same conn, name, and param parameters as the getPanel method. Those parameters are described in "Describing the ViewerPlugin and EditorPlugin Interfaces". The methods also have the following additional parameter.

• parent, which for the setValueChanged method is an implementation of the oracle.olap.awm.plugin.PanelChanged interface. That interface specifies a single method, public void changed();. Whenever the user interacts with the editing field of your EditorPlugin, the EditorPlugin should call the changed method of the PanelChanged object. For the other EditorPlugin methods, the parent parameter is the parent component.

Figure 2-6 Sequence of Calls to an EditorPlugin

Description of "Figure 2-6 Sequence of Calls to an EditorPlugin"

Elements in the params Map for a ViewerPlugin or EditorPlugin

The params Map for a ViewerPlugin or an EditorPlugin does not contain a BIND_MAP Map. Instead, the bind variables are keys in the params Map. Table 2-7 contains descriptions of the keys and values of the elements of the Map for a ViewerPlugin or an EditorPlugin.

Example params Map Elements for a ViewerPlugin and an EditorPlugin

Examples of the keys and values of a params Map for a ViewerPlugin or EditorPlugin are in Table 2-8. All of the values are String objects except those for the DATAPROVIDER and DATASOURCE keys.

measureobj = params.get("measureobj");

Object dp = params.get("DATAPROVIDER");

Object obj = null;
...
obj = params.get("dimobj");

Creating an XML Document for Descriptions of Plug-ins

1. Create a text file named awmplugin.xml.

2. Begin the file with an XML declaration like this one:

   <?xml version="1.0" encoding="utf-8"?>
   

   Specify the appropriate encoding for your site.

3. Enter the XML for the plug-in descriptions, as described in "Reference: Elements for Plug-in Descriptions".

4. For the name attribute of the <Plugin> element, enter a name for the plug-in. For the version attribute, enter the version number of the plug-in. For the class attribute, enter the class that contains the plug-in. For the <Description> element, enter a description of the plug-in.

5. In the plug-directory, create a JAR file that contains the awmplugin.xml document. Alternatively, you could add the awmplugin.xml document to a JAR file that contains the XML documents described in "Creating Reports in Object Folders" or the plug-ins.

For a sample awmplugin.xml file, see "Example of Plug-in Descriptions".

Reference: Elements for Plug-in Descriptions

An XML document for describing the available plug-ins has the format shown in Example 2-1.

<AWMPlugins>
  <Plugin>
    <Description>
         .
         .
         .