Chapter 3 Release Notes

These release notes contain:

• "Release and Version Issues"

• "Overview of the Product Documentation"

• "Working Directories"

• "Known Limitations"

Release and Version Issues

JMX Specification Compatibility

The Java Dynamic Management Kit version 4.2 is compatible with the JMX Instrumentation and Agent Specification, v1.0 (Final Release, July 2000). This is the current release of the JMX specification at the time the Java Dynamic Management Kit is shipping (December 2000).

The corresponding document can be viewed online once the documentation package has been installed (see "Overview of the Product Documentation").

Java Version Compatibility

The Java Dynamic Management Kit version 4.2 is officially supported for development platforms under the following configurations:

• Solaris 8 Operating Environment (SPARC Platform Edition), with Java 2 SDK, v1.2.2 Reference Implementation

• Windows NT 4.0 service pack 6 on Intel platform with Java 2 SDK, v1.2.2 Production Release for Windows NT

Deployment platform configurations are unsupported. However, the Java Dynamic Management Kit components are 100% Java code and should run with minimal modifications on environments compliant with Java Runtime Environment for Java 2, v1.2.2 or JDK 1.1.8. Many other configurations have been tested and are known to work reliably.

The Java Dynamic Management Kit 4.2 has been tested with Java 2 SDK (JDK 1.3.0) and no problems were encountered. JDK 1.1.x versions are provided as is but are not officially supported.

Backwards Compatibility

Versions 4.2 and 4.1 of the Java Dynamic Management Kit are fully communications-compatible: applications developed and running with version 4.1 can communicate with those developed and running 4.2. There is complete compatibility between agents using 4.1 and managers using 4.2. In the opposite case of an agent using 4.2 and a manager using 4.1, there is only a minor limitation with the connector heartbeat feature (see "Heartbeat Cross-Compatibility").

Versions 4.2, 4.1, and 4.0 of the Java Dynamic Management Kit are fully code-compatible: applications developed with version 4.1 and 4.0 will compile without modification when using version 4.2 of the packages. Some classes may cause compiler warnings about deprecation, but functionality is unchanged.

Due to major architectural changes, including the JMX compatibility, there is no communications-compatibility between version 4.2 of the Java Dynamic Management Kit and versions 4.0, 3.2, 3.0, and 2.0. Code developed for versions 3.2, 3.0, and 2.0 will most likely need to be ported in order to take advantage of the new architecture. Agents and managers developed with different versions of the product are definitely incompatible at the communications level, except for SNMP.

Due to its relatively stable protocol definition, SNMP can be used to connect applications developed with different versions of the Java Dynamic Management Kit, to the extent that the protocol was implemented by those versions. Agents or managers must continue to run their original version of the product, but they may communicate through SNMP with entities developed and running with different versions.

Files generated by the mibgen tool of the 4.2 release are compatible with those generated by the 4.1 version with one exception. The metadata classes generated for a MIB and used by the SNMP adaptor need to be regenerated. The other classes generated to represent the whole MIB and a skeleton implementation of each MIB group are unchanged, and they can be safely replaced by your previously customized implementations.

Cross-Java Compatibility

You must run all communicating agents and managers with the same major version of the Java Runtime Environment, either all using JDK 1.1 or all using Java 2. The behavior of a manager running Java 2 and communicating with an agent running the JDK 1.1, or vice-versa, is undefined. Data integrity and behavioral integrity are only possible when both agent and manager run the same version of the Java environment.

Again, SNMP interoperability has the advantage over other protocols of being independent of the Java environment version. The SNMP protocol adaptor can, regardless of its Java version, receive and decode requests from any SNMP manager. And a manager implemented with the SNMP manager API can send requests to any agent, without needing to know about its version compatibility.

Cross-Platform Compatibility

When product version compatibility and Java version compatibility are respected, the Java Dynamic Management Kit offers full management compatibility across heterogeneous platforms. For example, a manager running on a SPARC server could manage a whole deployment of Windows NT PCs, controlling their availability and upgrading their Java-technology based software when needed.

Overview of the Product Documentation

The Java Dynamic Management Kit product includes both printable and online documentation, as well as an exhaustive set of programming examples.

Online HTML Files

The HTML documentation is available after an installation of the product that includes the documentation package. On the machine where you installed the product, open the following URL in any browser:

This page contains links to all the product documentation supplied online with the Java Dynamic Management Kit, including:

• Getting Started with the Java Dynamic Management Kit 4.2

• Java Dynamic Management Kit 4.2 Tools Reference

• Java Dynamic Management Kit 4.2 Tutorial

• Java Dynamic Management Kit 4.2 Installation Guide and Release Notes (this document).

• The Java Dynamic Management Kit API specification generated by Javadoc^TM; the separate Collections API is also included in the JDK 1.1 version of the product.

• The JMX specification document.

Printable Documents

Complete PostScript^TM and PDF versions of the above books are supplied on the CD-ROM of the product. These files are located in the docs directory at the common root of the CD-ROM.

The documents are formatted for US Letter paper size (8.5 x 11 inches), but the they can be loaded by any appropriate document viewer or printed directly to any printer, regardless of the default paper size. The text area on each page will fit on all standard paper sizes.

Programming Examples

Sample applications which demonstrate most of the functionality of the Java Dynamic Management Kit are provided in the examples package of the product. If you installed this package, the Java source files and README text files for these applications are located in subdirectories under:

On the Solaris platform, writing to this directory requires super-user privileges. In order to compile the example programs, users should copy the examples hierarchy to a more accessible location.

The README file for each example gives a brief explanation of the source files and the instructions for running its application. Further explanation for most examples is given in the Java Dynamic Management Kit 4.2 Tutorial.

The examples directory also contains the JdmkProxyMBeans subdirectory which provides proxy MBeans for all of the Java Dynamic Management Kit components that support them. These are generated by the mibgen tool and will need to be compiled in the normal way before use. They can then be used to provide proxy objects in your manager applications for the agent-side service MBeans.

Working Directories

The installation of the Java Dynamic Management Kit creates directories that certain component services use by default. These directories are located under the Java version-specific branch of the installed directories, meaning that both Java versions of the product can be installed and run simultaneously. The following table shows the name and usage of these working directories (we show only Solaris path names, Windows NT folder names are identical):

If you install the Java Dynamic Management Kit in the default directory on a Solaris platform, installDir will be /opt. In this case, you will need super-user privileges to write the jdmk.acl file in the etc/conf directory.

Known Limitations

The following issues are known limitations of the Java Dynamic Management Kit 4.2 product at the time this document is being written (October 2000). Here, we explain the observed inconsistencies and suggest a workaround:

Heartbeat Cross-Compatibility

When a manager application running with version 4.1 of the product is communicating with agents running version 4.2, the heartbeat mechanism will cause an exception the second time the connect method is called. This behavior occurs in all connectors: RMI, HTTP, and HTTPS.

If you do not need the heartbeat functionality, you may avoid this limtation by disabling the heartbeat. If you do so, you must disable the heartbeat before the first connection, by setting the heartbeat period to 0 (zero). Once you have disabled the heartbeat, your connector client may connect and disconnect as many times as you wish.

If you would like to use the heartbeat functionality in this configuration, you should not establish more than one connection per connector client. The heartbeat mechanism is fully functional during the first connection. If you need establish a second connection after the first, you should disconnect and instantiate a new connector client for the second connection.

SNMPv2 Protocol

Report PDUs are not supported in the Java Dynamic Management Kit 4.2 because they are not presently defined by the standards (RFC 1905). Trap PDUs (both v1 and v2) and InformRequests are fully supported and should be used to send management information between agents and managers or between managers, respectively.

The HTML Adaptor

Due to the limitations of the HTML protocol, the HTML adaptor does not provide the same management view as a connector. For example, you cannot set attributes individually in the MBean view: all setters are called every time the "Apply" button is selected, even if the content hasn't changed.

Also, the HTML adaptor can only represent a limited set of types through an HTML interface. The values of attribute or operation results which rely on an unsupported type cannot be displayed or entered by the user. This means that some component functionality is inaccessible through the HTML adaptor.

HTTPS Heartbeat on Windows NT

The HTTPS connector client on the Windows NT platform may signal a false CONNECTION_REESTABLISHED notification, when its connector server is stopped. Thereafter, the correct CONNECTION_LOST notification is received. As this is due to timing issues, it is best to use a heartbeat period of five seconds or longer.

RMI Registry

Before starting a second RMI adaptor server in the same agent, you must launch an RMI registry for its intended port. Use the rmiregistry command line tool to do this, as explained in the JDK Tools online documentation (JDKinstallDir/docs/tooldocs/operatingEnv/rmiregistry.html). Failure to do so will prevent the second RMI adaptor server from starting.

Tutorial

The tutorial doesn't cover all of the sample applications found in the examples directory. All of the examples include detailed README files and well-commented code. In addition, certain topics can be found elsewhere:

• The MBean registration process is covered in the JMX agent specification.

• The monitoring and timer services are covered in the JMX specification.

• SNMP UserData is covered in the programming examples.

• SNMP RowStatus is covered in the programming examples.

JDK 1.1.8 and Native Threads

When running the JDK 1.1.8 virtual machine with native threads and using an HTTP connector client, an unexpected java.lang.ClassCastException is sometimes thrown. The workaround to this problem is to deactivate the keep-alive feature of the java.net.HttpURLConnection class. You can do this by running your application with the following property definition on the command line:

$ java -Dhttp.keepAlive=false yourApplication

Green Threads

Using green threads when running with a Java virtual machine other than a production release is also a known source of errors. Avoid using this combination to minimize the risk of unexplained failures. Please refer to the JDK documentation for more information about native and green threads.

M-Let with JDK 1.3 Software

When using the m-let service with the JDK 1.3 software, in particular when calling the method getMBeansFromURL(java.lang.String url) or getMBeansFromURL(java.net.URL url), a javax.management.ServiceNotFoundException is raised. This occurs because the JDK 1.3 APIs send HTTP/1.1 client requests and some HTTP server versions will reject all client requests that are not HTTP/1.0 or HTTP/0.9. Therefore, you need to ensure that your HTTP server accepts HTTP/1.1 client requests.

SnmpVarBind Status

In prior releases of the Java Dynamic Management Kit, the SnmpVarBind status was handed differently, depending upon whether you were using SNMP v1 or SNMP v2. This is no longer the case with the Java Dynamic Management Kit 4.2. The SnmpVarBind status handling has been modified to allow the user to perform status checking in the same way for both SNMP v1 and SNMP v2, although it may impact the Java code if you are using SNMP v2.

Now, regardless of the SNMP version you use to send a request, theSnmpVarBind status, as given by the getValueStatus method, always reflects the way that the SNMP request was sent (i.e. whether you used SNMP v1 or SNMP v2). Therefore, you may compare it with the constants stValueOk, stValueEndOfMibView, stValueNoSuchInstance, stValueNoSuchObject, or stValueUnspecified, which are defined in the SnmpVarBind class.