Sun Microsystems, Inc  Sun Microsystems, Inc 

JavaTM Dynamic Management Kit 5.1


Release Notes

These release notes contain important product notes and list known restrictions in the Java Dynamic Management Kit (Java DMK) 5.1. Details of workarounds to known bugs are given where possible. In cases where there are differences between these release notes and the Java DMK 5.1 documentation, the information in these release notes supersedes that in the documentation.

Table of Contents


Introduction

Java DMK 5.1 is a development tool kit for instrumenting managed resources and for building agent and manager applications in Java. It includes support for the Java Management Extensions (JMXTM) Maintenance Release 1.2 and the JMX Remote API, v1.0. These specifications define a three-level architecture:

The JMX architecture is applicable to network management, remote system maintenance, application provisioning, and the new management needs of the service-based network.

System Requirements

Java DMK 5.1 is officially supported on version 1.4 of the Java 2 Platform, Standard Edition (J2SETM).

However, Java DMK will operate on version 1.3 of the J2SE platform, provided certain other software is installed.

At the time of this release, version 1.5 of the J2SE platform has not yet been released. It is intended that Java DMK 5.1 will work with version 1.5 of the J2SE platform, which already includes the JMX, Secure Sockets Layer (SSL) Remote Method Invocation (RMI) socket factories, and Simple Authentication and Security Layer (SASL) APIs. It also includes the mandatory part of the JMX Remote API. If you are using version 1.5 of the J2SE platform, you therefore do not need to add the jmx.jar, jmxremote.jar, rmissl.jar, sasl.jar, and sunsasl.jar libraries to your classpath. You need only add the jdmkrt.jar and jdmktk.jar libraries to your classpath, as well as the jmxremote_optional.jar file if you wish to access the functionality of the optional part of JMX Remote API.

Validation of this release has been performed using J2SE 1.4.2_04 and J2SE 1.5.0 (Build 51), on the following platforms:

There should not be any dependency on a particular OS or hardware platform.


What's New in This Release?


The main new features added in Java DMK 5.1 are the following:

JMX 1.2 Compatibility

The Instrumentation and Agent services are now compatible with the latest JMX 1.2 Maintenance Release.

JMX Remote API 1.0 Compatibility

Java DMK version 5.1 implements the new connectors defined by the JMX Remote API 1.0 Specification. The connectors implemented in previous versions of Java DMK are retained for backwards compatibility.

The two new connectors are based on the RMI protocol, and a new protocol called the JMX Messaging Protocol (JMXMP). These new connector protocols allow more sophisticated secure and interoperable remote access to applications.

Connector Authentication and Privacy

Flexible authentication and privacy for connections is now available, based on the SASL 1.1 Specification, Transport Layer Security (TLS) for JMXMP-based connectors, and on SSL RMI socket factories and pluggable JMX authenticators for RMI-based connectors.

Connection authentication is provided by the following SASL mechanisms: PLAIN, DIGEST-MD5, CRAM-MD5, and GSSAPI/Kerberos.

Connection privacy is provided by the DIGEST-MD5 and GSSAPI/Kerberos SASL mechanisms.

Fine-Grained Access Control

You can now implement fine-grained access control, based on an authenticated client. User access is managed through the Java Authentication and Authorization Service (JAAS) and Java 2 platform Standard Edition (J2SE) Security Architecture.

Wrapping Java DMK 5.0 Connectors

Java DMK 5.1 allows for the wrapping of proprietary Java DMK 5.0 RMI and HTTP(S) connectors so that applications based on the standard JMX Remote API can interoperate with existing Java DMK-based applications. However, it is recommended that you implement the new RMI and JMXMP connector protocols defined by the JMX Remote API.

Enhanced Cascading Service

The cascading service has been completely overhauled in Java DMK 5.1 to allow it to operate over the connector protocols defined by the JMX Remote API. The legacy cascading service is now deprecated.

Enhanced Discovery Service

The discovery service has been enhanced, allowing the discovery of Java DMK based applications using legacy connectors as well as those using the new connectors.

SNMP API Repackaged

The Java packaging of the SNMP classes for Java DMK 5.1 has changed. In Java DMK 5.0, the SNMP classes were included in the SUNWjsnmp package, and they required a separate Java archive (JAR) file, jsnmpapi.jar. In Java DMK 5.1, the SNMP classes are packaged in the SUNWjdmk-runtime package, and require the same jdmkrt.jar JAR file as the rest of the current Java DMK classes. This new arrangement avoids the issue of potentially conflicting versions of the SUNWjsnmp package encountered under Java DMK 5.0.

In addition, the SNMP API delivered with Java DMK 5.0 is now deprecated. The SNMP API in Java DMK 5.1 is effectively a completely separate SNMP API, that introduces a more orthodox system of Java class naming.

To migrate existing SNMP implementations that you created using Java DMK 5.0 to the new Java DMK 5.1 package hierarchy, you must translate the class names of the 5.0 implementations into the new format. This translation can be performed by running the following ANT task:

<target name="replace" depends="">
<replace dir="<YOUR DIR>" token="com.sun.jdmk.snmp.UserAcl" value="com.sun.management.snmp.uacl"/>
<replace dir="<YOUR DIR>" token="javax.management.snmp" value="com.sun.management.snmp"/>
<replace dir="<YOUR DIR>" token="com.sun.jdmk.snmp" value="com.sun.management.snmp"/>
<replace dir="<YOUR DIR>" token="com.sun.jdmk.internal.snmp" value="com.sun.management.internal.snmp"/>
<replace dir="<YOUR DIR>" token="com.sun.jdmk.comm.Snmp" value="com.sun.management.comm.Snmp"/>
</target>

For more information about ANT, see http://ant.apache.org/.

To continue to use SNMP implementations you created using version 5.0 of Java DMK under version 5.1, a new JAR file called legacysnmp.jar, that contains the former Java DMK 5.0 classes, is provided. You must add this new JAR to your classpath when running your Java DMK 5.0 SNMP implementations under Java DMK 5.1. The new mibgen compiler also has an option that makes it possible to generate classes for use with the old Java DMK 5.0 packages.

Examples

New examples have been created and documented in the Java Dynamic Management Kit 5.1 Tutorial, to demonstrate the following:

In addition, all the existing examples have been reworked to demonstrate the use of the new JMX 1.2, JMX Remote 1.0, and Java DMK 5.1 APIs.

Features Deprecated Since 5.0

The following features have been deprecated since Java DMK 5.0.

Unsupported Contributions

The following unsupported contributions are supplied with Java DMK 5.1, although they are not officially parts of the product:

These contributions are found in directory the following directory, in which installDir represents the directory in which you installed Java DMK 5.1:

installDir/contributions

See the README file in this directory for details.


Known Bugs and Issues

The following is a list of known limitations and issues.

Interoperability

The following potentential interoperability issue has been identified:

Software Limitations

The following software limitations have been identified:

Documentation Limitations

The following documentation limitations have been identified:

Software Bugs and Issues

The following bugs have been recognized in relation to this release:

Bug ID Description
4717390 Using the MIB overlapping feature (the ability to register a MIB for a MIB subtree), there is a change in behavior between get and getnext requests. If the deepest registered MIB contains fewer oids than the MIB that is located above it, a getnext will return a varbind and a get will return a NoSuchObject.
4850443

Java DMK SnmpAdaptorServers will not be able to operate properly if, after having started the adaptor, the System date is set backwards to a date prior to the time at which the adaptor was started. This is because in such a case sysUpTime appears to be negative.

The SNMP adaptor will still be able to service incoming requests, but will be unable to send traps for which no timestamp is provided by the user until such a date where sysUpTime is positive again.

Setting the date forward does not cause the same problem because the sysUpTime counter will simply wrap around.

If you need to set the date backwards on your system, to a date which is before to the time at which the Java DMK SNMP adaptor was started, you should therefore first stop the adaptor, then set the date backwards, before restarting the adaptor.

Note the problem only occurs when the new date is anterior to the time at which the adaptor was started.

4953683

In certain cases, when a single SNMP SET request is used to create several rows, table data may not be correctly cleaned in the agent if the SET request fails.

This happens because row creation is actually performed in the check() phase of the SET two-phase commit, with activation of the row being performed in the set() phase.

During the check() phase, the SNMP runtime first determines whether new rows must be created by looking at the provided RowStatus variables. When a new row must be created, the runtime creates a new entry for that row, calls check() for that entry, and if no exception is raised, it adds the row to the table, leaving it in the notInService state.

If a single request is used to create several rows, the SNMP runtime will invoke check() on the first row to be created, adding it to the table and leaving it in the notInService state. Then it invokes check() on the second row to be created, adding it to the table and leaving it in the notInService state, and so on.

Then, if no exception was raised by any check() method, the set() phase begins for all rows: the values provided in the SET are applied to the new rows, and all new rows are activated.

The problem occurs when the check() for the first row succeeds, but the check() for the second row fails. In that case, the first row will not be removed from the table, but will remain in the table with a RowStatus positioned to notInService.

4977417 When using Model MBeans, setting the logging level to FINER will result in a huge amount of traces that can make trace manipulation difficult.
4997033 If the DescriptorSupport only defines getMyAttribute, calling RequiredModelMBean.setAttribute when there is no currencyTimeLimit, or when it is equal to -1, does not cause ServiceNotFoundException to be thrown.
5044821 If an SNMP Agent (Java DMK or otherwise) answers with an SnmpTooBig error and the SnmpSession options are correctly configured to handle toobig, the Java DMK manager API will not deal with the response correctly. It will enter an infinite loop that will resend the request endlessly.

Workaround:

On the manager side, call SnmpPeer.setMaxSnmpPktSize(agent packet max size). This will make the manager split the request before sending it.

5045159 Errors related to the com.sun.jdmk.snmp.threadnumber property are not logged properly. They are printed in System.err.