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.1 is compatible with the Java Management Extensions Instrumentation and Agent Specifications, v1.0, Public Release 2 (December 1999). This is the current release of the JMX specification at the time the Java Dynamic Management Kit is shipping (April 2000).

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

For historic reasons, the previous version of the JMX specification was identified as "Draft 2.0, First Public Release (August 1999)."

Java Version Compatibility

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

• Solaris 7 and Solaris 8, both SPARC and Intel Platform Editionswith Java 2 SDK, v1.2.2 Reference Implementationor JDK 1.1.8 Reference Implementation

• Windows NT 4.0 service pack 6a on Intel platformwith Java 2 SDK, v1.2.2 Production Release for Windows NTor JDK 1.1.8 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 with compliant 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.

Backwards Compatibility

Due to major architectural changes, including the JMX compatibility, there is no backwards compatibility between version 4.1 of the Java Dynamic Management Kit and previous releases (3.2, 3.0, 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.

Versions 4.1 and 4.0 of the Java Dynamic Management Kit are fully code-compatible: applications developed with version 4.0 will compile without modification when using version 4.1 of the packages. However, due to serialization issues, agent and manager applications of heterogeneous 4.x versions cannot communicate. This is easily solved by recompiling the 4.0 applications using the 4.1 packages.

One notable exception to version incompatibility at the communication level is the SNMP interoperability. Due to the relatively stable protocol definition, SNMP can be used to connect 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 relying on a different version.

Files generated by the mibgen tool of the 4.1 release are compatible with those generated by the 4.0 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 on-line documentation, as well as an exhaustive set of programming examples.

On-Line 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 on-line with the Java Dynamic Management Kit, including:

• Getting Started with the Java Dynamic Management Kit 4.1

• Java Dynamic Management Kit 4.1 Tools Reference

• Java Dynamic Management Kit 4.1 Tutorial

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

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

• The Java Management extensions, v1.0, Public Release 2, specification documents

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.1 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.1 product at the time this document is being published (April 2000). Here, we explain the observed inconsistencies and suggest a workaround:

SNMPv2 Protocol

Report PDUs are not supported in the Java Dynamic Management Kit 4.1 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 mangers or between managers, respectively.

The mibgen Tool

The mibgen tool cannot handle the row status construct. No error is generated and MIB compilation is not interrupted, but no special support is provided for the semantics of RowStatus variables (as defined in RFC 1903).

ACL Syntax

The Java Dynamic Management Kit 4.1 does not support a manager and trap host name of the form hostname.domain in an ACL file. You must use the host's corresponding IP address.

The use of localhost (or the corresponding IP address 127.0.0.1) as host name is not fully supported. You should use the specific hostname or IP address instead.

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.

Connector Server States

When a connector server cannot be started in an agent, it does not raise an exception or return an error, and it then falsely displays the ONLINE state. An agent or manager is lead to believe the connector server is active, but all attempted connections will fail. The most likely reason for a connector server to be unable to start is a port conflict. This occurs when the port it has been instructed to use, possibly the default port, has already been taken by another object.

RMI Registry

Before starting a second RMI connector server in the same MBean server on a different port, 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 on-line documentation (JDKinstallDir/docs/tooldocs/operatingEnv/rmiregistry.html). Failure to do so will prevent the second RMI adaptor server from starting, leading to the behavior described in the previous section.

RMI Service Names

Regardless of the port and the RMI registry, an RMI connector server created in its MBean server with a given RMI service name must be started before another RMI connector server can be created with a different service name. This applies to all RMI connector servers within the same JVM. If a second RMI connector server is created before the first is started, the RMI service name of the first will be changed to the value of the second, not the one it was given.

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.

• Proxy MBeans are introduced in Getting Started with the Java Dynamic Management Kit 4.0.

• The heartbeat mechanism in protocol connectors is covered in the Javadoc for the RmiConnectorClient class and demonstrated in the HeartBeat example.

• The secure HTTP connector and the secure class loading in the m-let service are covered in their respective Javadoc pages. These components also rely on the Java Secure Socket Extension 1.0 API and the javakey tool, respectively, which are documented on Sun's Java technology web site (http://java.sun.com).

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

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.