A proxy MBean is generated from its corresponding MBean by using the proxygen compiler supplied with the Java Dynamic Management Kit. A proxy MBean is an image of an agent-side MBean and exists on the manager side. The proxygen tool allows you to customize your proxy MBeans depending on how you want to use them in your management application. For more information regarding the relationship between MBeans and proxy MBeans, refer to Getting Started with the Java Dynamic Management Kit 4.1, which is part of this product documentation set.
The proxygen compiler takes the compiled Java class of an MBean and generates the Java interface and Java proxies of a MBean. The Java proxies consist of Java source code that implements the interface. To develop a Java manager with code generated by proxygen, you call the methods of the proxy MBean's interface.
Options of the proxygen compiler enable you to modify the characteristics of the proxies you generate from an MBean. For example, options are available that enable you to generate read-only or read-write proxies. By generating from the same MBean a set of proxies with different characteristics, you can develop a Java manager whose behavior is modified at runtime, depending on which proxies are loaded. For example, when the read-only proxies are loaded, the Java manager will not be able to modify properties in the MBean.
A proxy MBean consists of two components:
A Java interface that defines which of the operations of the MBean are accessible to a Java manager.
A Java class that implements the operations defined in the Java interface.
For example, if you have an MBean MyClass, the proxygen compiler gives you a proxy MBean that consists of the following files:
MyClassProxyMBean.java - the Java interface.
MyClassProxy.java - the Java class.
The proxygen compiler generates Java source code,
not compiled Java classes. For your proxy MBeans to be accessible to a Java
manager, you have to compile the files that proxygen generates,
and make sure that the compiled Java classes are stored at the location specified
by the CLASSPATH
environment variable
of the manager, or accessible through the class loader of the manager.
To start proxygen, type the command for your operating environment:
In a Solaris operating environment:
prompt% installDir/SUNWjdmk/jdmk4.1/JDKversion/bin/proxygen <options> <classes> |
In a Windows NT operating environment:
C:\> installDir\SUNWjdmk\jdmk4.01\JDKversion\bin\proxygen <options> <classes> |
Alternatively, you may invoke the java com.sun.jdmk.tools.ProxyGen class by first invoking java com.sun.jdmk.tools.ProxyGen <options> <classes>.
The following proxygen options include:
proxygen< options> <classes> |
where <options> include:
-d dir
Specifies a destination directory for the generated code
-ro
Generates read-only proxy MBeans
-tp pkgName
Generates code in the target package specified by pkgName
-classpath path
Specifies a classpath to use for locating the class to compile. By default, the system classpath will be used
-help
Prints a message that gives a brief description of each proxygen option
The following example shows how to generate the managed object for the Simple class and SimpleMBean interface, which is provided as an example with the Java Dynamic Management Kit. You must first call the Java compiler on the source code to obtain its .class file before using proxygen to generate the managed object. Finally, you must compile the Java code generated by proxygen.
The source code for the Simpleclass is contained in the installDir/SUNWjdmk/jdmk4.1/JDKversion/examples/MonitorMBean directory, where installDir is the directory under which the Java Dynamic Management Kit was installed.
On the Solaris platform, the installDir file hierarchy is not writable by default. In this case, you will first have to copy the Simple.java and SimpleMBean.java files to a directory where you have write permissions.
Before continuing, you need to set your CLASSPATH as follows:
In a Solaris operating environment:
prompt% installDir/SUNWjdmk/jdmk4.1/1.2/lib/jdmkrt.jar and jdmktk.jar |
In a Windows NT operating environment:
installDir\SUNWjdmk\jdmk4.1\1.2\lib\jdmkrt.jar and jdmktk.jar |
In a Solaris operating environment:
installDir/SUNWjdmk/jdmk4.1/1.1/lib/jdmkrt.jar and jdmktk.jar |
/SUNWjdmk/jdmk4.1/1.1/lib/collections.jar |
In a Windows NT operating environment:
installDir\SUNWjdmk\jdmk4.1\1.1\lib\jdmkrt.jar and jdmktk.jar |
\SUNWjdmk\jdmk4.1\1.1\lib\collections.jar |
prompt% javac SimpleProxy.java SimpleProxyMBean.java |
Type these commands:
prompt% javac Simple.java SimpleMBean.java prompt% /.../bin/proxygen/proxygen -classpath . Simple Destination directory set to ./. Starting compilation of Simple. Starting to generate stub SimpleProxy.java for class Simple Starting to generate MBean interface SimpleProxyMBean.java for class Simple |
For an MBean defined in the Java class BeanName, the proxygen compiler generates:
A Java interface (BeanNameProxyMBean), which defines the methods of the MBean that are accessible to a Java manager.
A Java proxy (BeanNameProxy), which implements the methods defined in the Java interface BeanNameProxyMBean.
For example, when an MBean representing a Java class named Simple is compiled, proxygen generates the source code of:
A Java interface named SimpleProxyMBean.
A Java class named SimpleProxy, which implements the SimpleProxyMBean interface.
The proxygen compiler uses the Java Reflection API for analyzing an MBean and generating its associated proxy MBean. It parses an MBean using the JMX-specific design patterns. The mapping rules that proxygen uses for generating the proxy MBean are described in the following subsections.
proxygen generates code only for exposed operations of the MBean itself. Each attribute of the MBean is present in the proxy MBean with the same accessor getter and setter methods. Therefore, if an attribute is read-only in the MBean, the property is read-only in the generated proxy MBean.
In addition to the attribute accessors, proxygen generates code only for exposed operations of the MBean itself.
The proxy MBeans that proxygen generates also contain methods that are not present in the MBean. Rather, they are defined in the Java interface com.sun.jdmk.Proxy. The proxy MBean generated implements this interface. These methods are public methods that do not follow the design patterns defined by the JavaBeans component model.
These methods provide additional functionality for proxy MBeans and the management applications which instantiate them. Their purpose is to:
Make sure that the information provided by proxy MBean is up to date. For example, methods are defined for binding and unbinding a proxy MBean from a remote MBean server.
Get the object name and class of the remote MBean represented by the proxy MBean.
The proxygen compiler generates Java source code that you use for developing Java managers. To develop a Java manager by using code generated by proxygen, you use the RemoteMBeanServer interface. Using the RemoteMBeanServer interface enables you to develop Java managers without having to modify the code that proxygen generates. However, you can also modify the code that proxygen generates if you want to define a specific view of an MBean.
The proxygen compiler generates Java source code, not compiled Java
classes. For your proxy MBeans to be accessible to a Java manager, you have
to compile the files that proxygen generates, and make
sure that the compiled Java classes are stored at a location specified in
the CLASSPATH
environment variable
of the manager, or are accessible through the class loader of the manager.
If you want to define a specific view of an MBean, you can modify the generated code. To ensure that the modified code remains consistent with the MBean it represents, do not modify the interface; modify only the proxy.