Sun Microsystems
Products & Services
 
Support & Training
 
 

Previous Previous     Contents     Index     Next Next
Chapter 3

Legacy MBean Proxy Generator (proxygen)

You can use the proxygen tool supplied with the Java Dynamic Management Kit (Java DMK) to generate a proxy MBean from its corresponding MBean. A proxy MBean is an image of an agent-side MBean that 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 about the relationship between MBeans and proxy MBeans, see the Java Dynamic Management Kit 5.1 Getting Started Guide.


Note - The proxygen tool is marked as "deprecated" in Java DMK 5.1. Use the proxygen tool only if you require proxies for legacy remote method invocation (RMI), hypertext transfer protocol (HTTP), and secure HTTP (HTTP/S) connectors. For new RMI, RMI/IIOP and Java Management Extensions messaging protocol (JMXMP) connectors that comply with the JMX 1.2 and JMX Remote API 1.0 specifications, you can generate a proxy object at runtime, given just its Java interface. These dynamic proxies cannot be used with the legacy connectors. For more information on dynamic proxies, see the Java Dynamic Management Kit 5.1 Tutorial.


This chapter describes how to use the proxygen tool, in the following sections:

3.1 Overview of the proxygen Tool

The proxygen tool takes the compiled Java class of an MBean and generates the Java interface and Java proxies. 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 tool enable you to modify the characteristics of the proxies you generate from an MBean. For example, with some options, you can 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 cannot modify properties in the MBean.

A proxy MBean consists of two components:

  • A Java interface that defines which 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 tool gives you a proxy MBean that consists of the following files.

  • MyClassProxyMBean.java: the Java interface

  • MyClassProxy.java: the Java class

The proxygen tool generates Java source code, not compiled Java classes. For your proxy MBeans to be accessible to a Java manager, you must compile the files that proxygen generates. Then you must make sure that the compiled Java classes are stored at the location specified by the CLASSPATH environment variable of the manager, or are accessible through the class loader of the manager.

3.2 Starting the proxygen Tool

To start the proxygen tool, type the command for your operating environment:

prompt% installDir/SUNWjdmk/5.1/bin/proxygen <options>  <classes>

Alternatively, invoke the java com.sun.jdmk.tools.ProxyGen class by first invoking java com.sun.jdmk.tools.ProxyGen <options> <classes>. Provide the class name without the .class extension.


Note - The script for starting the proxygen tool uses the JAVA_HOME environment variable to determine the path to the Java 2 Platform Standard Edition (J2SE). Therefore, even if you have the correct path to the J2SE platform in your PATH environment variable, this setting is overwritten by the JAVA_HOME variable.


3.3 proxygen Tool Options

The proxygen command takes options, as follows:

proxygen options classes

The options include the following.

-d dir

Specifies a destination directory for the generated code.

-ro

Generates read-only proxy MBeans. Calling setter methods of these read-only proxies raises a com.sun.jdmk.RuntimeProxyException.

-tp pkgName

Generates code in the target package specified by pkgName.

-classpath path

Specifies a class path to use for locating the class to compile. By default, the system class path is used.

-help

Prints a message that briefly describes each proxygen option.

3.4 Example of the proxygen Tool

The following example shows how to generate the managed object for the Simple class and SimpleMBean interface. You must compile the classes before using the proxygen tool to generate the managed object. Finally, you must compile the Java code generated by the proxygen tool.

The source code for the Simple class is contained in the installDir/SUNWjdmk/5.1/examples/legacy/MonitorMBean directory, where installDir is the directory under which the Java DMK was installed.


Note - On the Solaris platform, the installDir file hierarchy is not writable by default. In this case you must copy the Simple.java and SimpleMBean.java files to a directory where you have write permissions.


ProcedureTo Generate the Managed Object for the Simple Class

  1. Add the following to your CLASSPATH:

    • In the Solaris or Linux operating environment.
      installDir/SUNWjdmk/5.1/lib/jdmkrt.jar  
      installDir/SUNWjdmk/5.1/lib/jdmktk.jar
      installDir/SUNWjdmk/5.1/lib/jmx.jar

    • In a Windows 2000 operating environment.
      installDir\SUNWjdmk\5.1\lib\jdmkrt.jar
      installDir\SUNWjdmk\5.1\lib\jdmktk.jar
      installDir\SUNWjdmk\5.1\lib\jmx.jar

  2. Type the following commands.

    prompt% javac Simple.java SimpleMBean.java
    prompt% /.../bin/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

    Proxy MBeans generated using the proxygen tool in Java DMK 4.2 must be regenerated to run in Java DMK 5.1, because some of the methods used in version 4.2 have been deprecated. However, proxy MBeans generated using the proxygen tool in Java DMK 5.0 do not need to be regenerated to run in Java DMK 5.1.

Previous Previous     Contents     Index     Next Next