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.
%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
To compile, package and deploy the components of this application
simply type
the following command from a command prompt in the root
directory of the sample:
>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
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.
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
OC4J supports the use of startup (and shutdown) classes to inject operations when OC4J is in its various lifecycle phases. The use of an OC4JStartup class can be used to register JMX MBeans in the different phases such as postDeploy and preDeploy, by employing a custom MBeanServer. Once created, the custom MBeanServer can be viewed from ASC and its MBeans interacted with.
Bookmark
