How To: Register MBeans on Container Startup

                          $Id: readme.html 592 2006-08-16 00:21:17Z tgrall $ $Date: 2006-08-15 17:21:17 -0700 (Tue, 15 Aug 2006) $
                      

• Introduction
• What are the Prerequisites?
  • What Should You Know?
  • What are the Software Requirements?
  • What are the Notations?
• How to Build the Application?
  • Examining the Distribution
  • Setting up the Application
  • Configure the Server with the Startup Class
  • Starting OC4J
• Viewing the MBean
• Developing the Solution
• Summary

Change Tracking

Introduction

In some circumstances, it may be necessary to register MBeans (or perform other JMX operations) at certain places within the OC4J initialization or shutdown lifecycle. This can be accomplished using a combination the OC4J startup/shutdown classes and the JMX API to both create a custom MBeanServer and programmatically register the required MBean classes in the custom MBeanServer.

What are the Prerequisites?

What Should You Know?

• Be generally familiar with J2EE and its associated JMX capabilities.
• Know what an OC4J startup class is and when it would be useful to employ.

What are the Software Requirements?

• OracleAS or OC4J 10g (10.1.3) installed. Available from OTN.
• Sun JDK 1.5. Available from the Sun Web site.

What are the Notations?

• %ORACLE_HOME% : the directory in which OC4J has been installed.
• %J2EE_HOME% : the directory where the oc4j.jar file exists within OC4J.
  This is typically 2 directories under %ORACLE_HOME%. For example, if you installed OC4J to c:\ then %J2EE_HOME% would be c:\j2ee\home
• %JAVA_HOME% : the directory where the JDK is installed on your machine.

How to Build the Application?

This how-to needs to be built and deployed before it can be accessed. It is not delivered in a ready-to-deploy manner. However the build process is relatively simple thanks to the wonder of Ant.

Examining the How to Distribution

First off, let's examine the contents of the how-to distribution.

The src directory contains the Java code for the OC4JStartup class and the example MBean.

PostDeployMBeanRegister is the class which implements the OC4JStartup interface.

MyExampleMBean is the interface for the MBean we are using.

MyExample is the implementation of the MBean interface.

Since this how-to is demonstrating the use of an OC4JStartup class, its elements are quite simple. An OC4JStartup class is a container level resource and is applied to a server in a simple JAR file. This means there is no need for the use of any deployment descriptors.

The MBean used in this example is only ever used by the OC4JStartup class, so it can be deployed within the same JAR file as the OC4JStartup class.

The build.xml file is the main Ant build file that will compile and package the classes into a JAR file.

Setting Up the Application

Make sure the following properties are configured correctly in the oracle-ant.properties file located in the root directory of this how-to distribution.

NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file.  If necessary, modify these variables to the proper values for you environment:

• oracle.home - the root directory of oracle installation.  Defaults to the ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas.host - the hostname of the platform on which the target OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas..admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to "oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to "welcome1".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to "http-web-site"
• oracleas.deployer.uri - identifies the target for deployment operations -- enables OC4J standalone, OracleAS single instance or an OracleAS group to be deployed to using the same set of Ant tasks

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

Build the Application

>ant

Executing the default all target of the supplied build.xml file performs the following steps:

• Compiles all the source files
• Packaged the class files into a JAR file
• Copies the resulting JAR file into the %ORACLE_HOME%/j2ee/home directory

Configure the Server with the Startup Class

Once the example has been built and packaged, the server can be configured with the startup class details,

Edit the %ORACLE_HOME%/j2ee/home/config/server.xml file and add the following entries

                                <init-library path="../how-to-startup-mbeans.jar" />

                                <startup-classes>
  <startup-class classname="
                               demo.oc4j.startupmbeans.startup.PostDeployMBeanRegister" failure-is-fatal="true" >
    <execution-order>0</execution-order>
    <init-param>
      <param-name>
                               mbean_server_name</param-name>
      <param-value>
                               StartupMBeanServer</param-value>
    </init-param>
  </startup-class>
                                </startup-classes>
    
                            

There are two separate elements in the configuration text to be added:

<init-library> adds a library to OC4J which is used to load startup (and/or shutdown) classes.

<startup-classes> defines a set of classes to be invoked during the container startup phase. Parameters can be passed to startup class instances using the <init-param> tag. In this case, the mbean_server_name parameter is set with a value of StartupMBeanServer. This parameter is retrieved in the startup class and used as the name of the custom MBeanServer that is created.

Start OC4J

With the required entries added to server.xml file, OC4J can be started.

Start your OC4J 10.1.3 instance as follows:

>%ORACLE_HOME%/bin/oc4j start

Note that the oc4j.cmd script expects the JAVA_HOME environment variable to point to a full JDK installation.

If the startup class is correctly configured, the console should contain messages showing the startup class operating.

C:\java\oc4j-10131-dev\j2ee\home>java -jar oc4j.jar
                              

06/08/14 15:50:10 demo.oc4j.startupmbeans.startup.PostDeployMBeanRegister::preDeploy
                              

06/08/14 15:50:17  
                               demo.oc4j.startupmbeans.startup.PostDeployMBeanRegister::postDeploy
                              

06/08/14 15:50:17    
                               creating MBeanServer("StartupMBeanServer")
                              

06/08/14 15:50:17    
                               registering MBean(":name=MyExampleMBean")
                            

Viewing the MBean

With the startup class configured correctly and OC4J started, the MBeanServer will be created and the MyExampleMBean registered within it.

Using Application Server Control (ASC) the custom MBeanServer and MBean can be viewed.

Open a browser window and enter the URL:

Custom MBeanServer instances can be viewed from the Application MBean Browser.

1.	Click in the Applications tab Click the Application Defined MBeans icon for the ascontrol application to display the Application MBean Browser.
2.	The Application MBean Browser will show the custom MBeanServer that was created by the startup class. The name of the MBean will match the mbean_server_name parameter, StartupMBeanServer in our example configuration. Expand the StartUpMBeanServer Select the MyExampleBean entry. The MyExample MBean will be displayed, showing the DateAndTime attribute that is exposed by the MBean.

Developing the Solution

There are several concepts to take into account here.

The area of OC4JStartup classes is documented in the OC4J Developer's Guide -- http://download-west.oracle.com/docs/cd/B25221_03/web.1013/b14433/startclas.htm.

Since a startup class is a container level resource, it does not have automatic access to the application specific MBeanServer created for applications to use. It must create its own MBeanServer if it needs to perform JMX based operations, and register MBeans within it.

public String  
                               postDeploy(Hashtable params, Context arg1) throws Exception {

  MBeanServer mbs;
                              

  String mbsName = DEFAULT_MBEANSERVER_NAME;

  System.out.println(getClass().getName() + "::postDeploy");
                              

  // See if the name of the MBeanServer was specified as
  // a parameter to the startup-class
  if(params.keySet().contains(MBEAN_SERVER_PARAM)) {
    mbsName = (String)params.get(MBEAN_SERVER_PARAM);
  }
                              

  // Create a custom MBeanServer
  System.out.println(" creating MBeanServer(\""+mbsName+"\")");
                              

  
                                mbs = MBeanServerFactory.createMBeanServer(mbsName);
                              

  // Create the object to register as the MBean
  MyExample myExample = new MyExample();
                              

  // Create the ObjectNme for the MBean
  ObjectName mbeanName = new ObjectName(MBEAN_NAME);

  // Register the MBean in the MBeanServer
                              

  System.out.println(" registering MBean(\""+mbeanName+"\")");
  
                                mbs.registerMBean(myExample, mbeanName);
                              

  return "postDeploy: success";
                              

}
                            

The MBean example used in this application is a trivial example of a Standard MBean.

public  
                               interface MyExampleMBean {
                              

    public String getDateAndTime();
                              

}

public  
                               class MyExample implements MyExampleMBean {
                              

  static final DateFormat FORMATTER = 
  DateFormat.getDateTimeInstance(DateFormat.DEFAULT, DateFormat.SHORT); 

  /**
   * Represents the attribute DateAndTime for the MBean
   * @return Date and Time in String form
   */
                              

  public String getDateAndTime() {
                              

    Date now = new Date(System.currentTimeMillis());
                              

    return FORMATTER.format(now);
                              

  }
                              

}
                            

Summary