Extending the Administration Console

Using Oracle Templates and JSP Tags

This section describes how to add a portlet that uses the Administration Console’s JSP templates, styles, and user input controls. For example, you can add portlets that render your content as one of the following:

Figure 7-1 illustrates the process. The steps in the process, and the results of each are described in Table 7-1. Subsequent sections detail each step in the process.

Create and Use a Message Bundle in Your JSPs

Oracle recommends that you define all of the text strings that your JSPs display in a message bundle. For information about creating a message bundle, see Creating a Message Bundle.

To use the bundle in your JSPs:

Overview of Forms and Tables

WebLogic Server provides a <wl:form> JSP tag that can render a variety of HTML input controls, such as text controls, check boxes, and radio controls. You can configure a form to be read-only or to allow user input. Forms that allow user input must include buttons that enable users to post the form data for processing in the business layer.

WebLogic Server provides a <wl:table> JSP tag that renders data in a tabular format. Each row in the table represents a single entity such as a WebLogic Server instance, an application, or a log message (see Figure 7-2). You can configure table columns to render hypertext links, which enable users to navigate to pages that provide more information about an item in the table. You can also create a table column that contains an HTML check box control. If a user selects a check box for a table row and clicks a submit button, your extension can invoke business logic on behalf of the entire row. For example, you can use a check box to delete an item that a row represents.

Both of these tags use Apache Struts Actions and ActionForms to pass data between the business layer and the presentation layer.

Data Models for Forms and Tables

Apache Struts supports multiple techniques for instantiating and populating ActionForm beans (form beans). For example, you can code your own concrete Java bean that contains getter and setter methods for each property in the form. Or you can use the Struts DynaActionForm bean, which dynamically configures a Java bean to contain the properties that are declared in the Struts configuration file.

Data Model for Forms

If you are using Oracle JSP tags to render a form in the Administration Console, you can use any technique for creating and populating form beans that Struts supports. (The example in Example: How Struts Portlets Display Content uses a DynaActionForm bean instead of coding a custom Java bean.)

Regardless of the technique that you choose, your Java bean must contain the following property:

Data Model for Tables

If you are using Oracle JSP tags to render a table in the Administration Console, you must create two form beans: one bean that represents the rows in the table (called a row bean) and another bean (called a table bean) that contains the collection of row beans. Each property in the row bean is rendered as a table column. For example, in Figure 7-2, each row bean instance contains a name, state, health, and listenPort property.

To create a row bean, you must create a concrete Java bean that defines each property. You cannot use the Struts DynaActionForm bean to dynamically contain the properties that are declared in the Struts configuration file.

To create a table bean, you can use any technique for creating and populating form beans that Struts supports. Regardless of the technique that you choose, your table bean must contain the following properties:

If you configure your table to include a column of check boxes, which enables you to invoke a Struts Action on the selected table row beans, your table bean must also contain the following property:

Handles for ActionForms and Row Beans

To uniquely identify an instance of an ActionForm bean or a row bean and to establish a correlation between the bean and its underlying data source, you can create and use a Handle object. A Handle object is a Java object that implements the com.bea.console.handles.Handle interface.

The Apache Struts controller servlet places Handle objects in HttpServletRequest objects, thus making them available to any Struts Action, Beehive Page Flow, or JSP.

The Administration Console uses Handle objects when linking from a row in a table JSP (see Figure 7-2) to the corresponding configuration JSP. For example, for a ServerMBean instance named Server-0, the Administration Console populates row bean with data from the Server-0 MBean. The Administration Console passes the JMX object name for Server-0 to a new a Handle object (of type com.bea.console.handles.JMXHandle) and sets the Handle object as the value of the row bean’s handle property (see Figure 7-3). When a user clicks a link in the table JSP, the Struts controller looks in the row bean’s handle property, uses the handle value to determine which server instance has been selected, and displays the configuration page for the selected server.

If the underlying data source for your ActionForm beans or row beans is an MBean, you can use the com.bea.console.handles.JMXHandle object. See JMXHandle in the Administration Console API Reference.

If the underlying data source for your beans is not an MBean, you can create your own Java class that implements the com.bea.console.handles.Handle interface. See Handle in the Administration Console API Reference.

Create Struts Artifacts for Tables and Forms

To render HTML forms and tables and populate them with data, the Administration Console uses JSP tags that load data from Java beans. Most of these beans contain data that a Struts Action has loaded from a WebLogic Server MBean. To submit user input, the JSP tags forward to Struts Actions, and most of these Actions update data in a WebLogic Server MBean.

If you use Administration Console JSP tags, you must create your own Struts ActionForms and Actions.

The following sections describe creating Java beans, Struts Actions, and ActionForms to use with forms and tables:

For information on Apache Struts, see The Apache Struts Web Application Framework at http://struts.apache.org/.

Create Struts Artifacts for a Form JSP: Main Steps

To create Struts artifacts that pass data between the business layer and a JSP in the presentation layer:

Create Struts Action Classes for Handling Form Data

To create Struts Action classes that handle form data:

Listing 7-1 is an example org.apache.struts.action.Action class that accesses a custom MBean and uses it to populate a form bean.

import javax.management.MBeanServer;
import javax.management.ObjectName;
import javax.management.MalformedObjectNameException;
import javax.naming.InitialContext;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.struts.action.DynaActionForm;
import org.apache.struts.action.Action;
import org.apache.struts.action.ActionForm;
import org.apache.struts.action.ActionForward;
import org.apache.struts.action.ActionMapping;

public class MedRecMBeanFormAction extends Action {
   public ActionForward execute(ActionMapping actionMapping,
                                 ActionForm actionForm,
                                 HttpServletRequest httpServletRequest,
                                 HttpServletResponse httpServletResponse)
      throws Exception {
      try {
         // Establish a local connection to the Runtime MBean Server
         InitialContext ctx = new InitialContext();
         MBeanServer server = 
            (MBeanServer) ctx.lookup("java:comp/env/jmx/runtime");
         // Create an ObjectName that corresponds to a custom MBean that
         // has been registered in the Runtime MBean Server
         ObjectName anMBean = new ObjectName(
            "com.bea.medrec:Type=com.bea.medrec.controller.
              RecordSessionEJBMBean,Name=MedRecEAR");
         //Get the value of the custom MBean’s “Name” attribute
         String namefromMBean = (String)server.getAttribute
            (anMBean, "Name");
        // Get the value of the custom MBean’s “TotalRx” attribute
         Integer totalRxfromMBean = (Integer) server.getAttribute
            (anMBean, "TotalRx");

        // Populate the form bean
        DynaActionForm form = (DynaActionForm) actionForm;
        form.set("name",namefromMBean);
        form.set("totalRx",totalRxfromMBean);
        form.set("handle",(new JMXHandle(anMBean)));

        // Set the form bean in request. The name of the 
        // form bean must match the “form-bean” name in your
        // Struts configuration file
        httpServletRequest.setAttribute("medrecMBeanEJBForm", form);
      } catch (Exception ex) {
          ex.printStackTrace();
      }
      return actionMapping.findForward("success");
   }
}

Configure Struts ActionForms and Action Mappings

To create a Struts configuration file that declares your ActionForms and Action mappings:

Create Struts Artifacts for a Table JSP

To create a Java row bean, Struts Action, and ActionForm for a JSP that uses the WebLogic Server <wl:table> JSP tag:

Create JSPs that Use Oracle Templates and JSP Tags

Most portlets in the Administration Console JSPs that are based on the tableBaseLayout_netui and configBaseLayout_netui templates.

The following sections describe how to create JSPs that use these templates:

WebLogic Server JSP Templates

Table 7-2 describes the JSP templates that you can use for your Administration Console extensions. All of the templates are located in the /layouts directory, which is relative to the WEB-INF directory of the Administration Console. WebLogic Server does not publish the templates themselves, but Using Oracle Templates and JSP Tags describes how to use them.

If these templates do not meet your needs, you can create your own templates and structure the content directly in your JSP.

Create a Form JSP

Before you create a form JSP, create Struts artifacts that pass data between the business layer and the JSP. See Create Struts Artifacts for a Form JSP: Main Steps.

To create a form JSP (see Listing 7-4):

Create a Table JSP for Monitoring

Before you create a table JSP, create Struts artifacts that pass data between the business layer and the JSP. See Create Struts Artifacts for a Table JSP.

To create a table JSP for monitoring resources (see Listing 7-5):

Create a Table Column for Navigating to Other Pages

Your table JSP can provide a link from each row to a configuration page or some other related page. The linking mechanism uses a Handle object to determine which pages are related to a specific table row (see Handles for ActionForms and Row Beans).

You can use any of the following JSP tags to link from a table:

The following sections describe how to create a table column for navigating:

Add a Handle to Your Row Bean and Action Class

To create and populate a handle property:

Use the column-link Tag

To use the <wl:column-link> tag:

Use the column-dispatch Tag

To use the <wl:column-dispatch> tag:

Add Buttons and Checkboxes to Tables

In a table that you create using the <wl:table> tag, you can use buttons by themselves or in conjunction with a column of checkboxes or radio buttons.

When used by themselves, buttons can forward to page UI control. For example, in the WebLogic Server Servers table (see Figure 7-2), users click on a New button to launch the Create a Server assistant.

When used in conjunction with a checkbox, buttons can process data on behalf of one or more table rows. For example, if each row in your table represents an instance of a custom MBean that provides monitoring data for your application, you can enable users to select a checkbox for one or more rows and click a button that resets the values in the corresponding MBean instances.

The following sections describe adding checkboxes and buttons to tables:

Add Buttons to a Table

To add buttons to a table:

Add Checkboxes and Buttons to a Table

To process data on behalf of one or more table rows, use checkboxes and a button to post the data to an HTTP request. You must also create a Struts Action or Page Flow that can retrieve and process the posted data:

Example: How Checkboxes and Buttons Process Data

The following steps describe a table that correlates a table row with an underlying MBean data source and clears the values of attributes in the MBean:

Configure Table Preferences

By adding a single attribute to the <wl:table> tag, you can enable your users to configure which table columns the table displays. The Administration Console persists the preference for each user and for each instance of the portlet that displays the table. If you reuse a table in multiple portlet instances, each user can set a different preference for the table in each portlet instance.

To enable users to configure the set of table columns that your table displays, add the following attribute to your <wl:table> tag: customize=”true”.

For example:

<wl-extension:table
    customize="true"
...
>

When the Administration Console displays the JSP that contains the table, it renders a “Customize this table” link above the table title. The link causes the table JSP to display a section that contains a chooser control and an Apply or Reset button.

Create Other Portal Framework Files and Deploy the Extension

You can add your portlet directly to the desktop, but if you want your portlet to display as a tab or subtab in the ContentBook, you must define books or pages to contain it. In addition, you must create a netuix-extension.xml file which specifies where to locate your portlet, books, and pages and which functions as the deployment descriptor for your extension.

See Adding Portlets and Navigation Controls.