# # @(#)file RELEASE_NOTES # @(#)author Sun Microsystems, Inc. # @(#)version 1.9 # @(#)date 02/06/18 # # Copyright © 2002 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # ---------------------------------------------------------------------------- Java(TM) Dynamic Management Kit 5.0 Release Notes ---------------------------------------------------------------------------- These release notes contain important product notes and list known restrictions in the Java(TM) Dynamic Management Kit (DMK) 5.0. 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.0 documentation set, the information in these release notes supersedes that in the documentation set. Contents ~~~~~~~~ I. Enhancements and Major Changes in This Release II. Release and Version Issues III. Product Notes IV. Known Limitations V. Documentation Errata and Addenda =================================================== I. Enhancements and Major Changes in This Release =================================================== Java Management Extensions (the JMX(TM) Specification) ------------------------------------------------------ The Java DMK 5.0 conforms to the Java Management Extensions (the JMX Specification), v1.1 Maintenance Release, March 2002. The corresponding specification document can be viewed once the documentation package has been installed. SNMPv3 ------ This is a major new feature. The Java DMK 4.2 supports SNMPv1 and SNMPv2. The Java DMK 5.0 supports SNMPv1, SNMPv2, and SNMPv3, including the ability for a single agent to respond to requests from different SNMP versions. The SNMPv3 implementation is based on RFCs 2571, 2572, 2574, and 2576. The Java DMK 5.0 supports SNMPv1, SNMPv2c and SNMPv3 message processing models. The Java DMK 5.0 supports the user-based security model (USM): - USM MIB - Authentication (HMAC MD5 and HMAC SHA) - Privacy (DES). RFC 2573 (applications) is not supported in this release. RFC 2575, which specifies the view-based access control model (VACM), is not fully supported in this release. Access control is possible based on five of the six parameters defined by the VACM, the missing one being the object instance. Access control is based on an ACL file with a proprietary syntax. No MIBs are provided to update the configuration remotely. When a getBulk request is forwarded to an SNMPv1 subagent, the maxRepeat and nonRepeat parameters are not just reset as specified in RFC 2576, section 4.2.1. In the Java DMK 5.0, the getBulk request is completely forwarded by a series of getNext requests. SNMP Interfaces --------------- A few Java interfaces used for fine-grained treatment of SNMP requests have acquired extra methods in the Java DMK 5.0 to deal with SNMPv3. Therefore, user code that implements those interfaces will need to be extended to implement the new methods. Relatively little code is likely to be affected, and the changes to make are generally obvious. SNMP Master Agent ----------------- The SNMP master agent feature incorporated in the Java DMK 5.0 includes a fully implemented version of the SNMP proxy class (SnmpMibAgentImpl) that was demonstrated by the SNMP proxy example in version 4.2 of the Java DMK. It allows forwarding of received SNMPv1, SNMPv2, and SNMPv3 requests via SNMPv1, SNMPv2, and SNMPv3. The SNMP master agent feature incorporated in this release is NOT the proxy forwarder application defined in RFC 2573. See the section entitled "SNMP Master Agent and the SNMPv3 Proxy Forwarder" in Chapter 21 of the "Java Dynamic Management Kit 5.0 Tutorial" for more detailed information. SNMP Manager API Classes (jsnmpapi.jar File) ------------------------ For Users of the Solaris(TM) Operating Environment -------------------------------------------------- In the Java DMK 5.0, the SNMP manager API classes are no longer provided in the same Java archive (JAR) file and same package as the other runtime classes. The SNMP manager API classes are now provided in the jsnmpapi.jar file, in the SUNWjsnmp package, and the other runtime classes are provided in the jdmkrt.jar file, in the SUNWjdrt package. See also the section "Dependency of the SUNWwbcou Package on the SUNWjsnmp Package" in Part IV "Known Limitations". For Users of Windows 2000 ------------------------- In the Java DMK 5.0, the SNMP manager API classes are no longer provided in the same JAR file as the other runtime classes. The SNMP manager API classes are now provided in the jsnmpapi.jar file, and the other runtime classes are provided in the jdmkrt.jar file. Open MBeans ----------- The Java DMK 5.0 includes an implementation of open MBeans, as specified in the JMX specification, v1.1 Maintenance Release. MBean Interceptors ------------------ The Java DMK 5.0 relaxes the requirement that every MBean (managed object) in a Java DMK agent must be represented by a Java object in that agent. MBean interceptors make it possible to intercept operations on MBeans and handle them arbitrarily. Handling them might involve handing the request on to other interceptors, perhaps after logging it or vetting it for security. Alternatively, it might involve treating the request directly. For instance, with very volatile MBeans, this avoids having to keep up with creations and deletions of objects. Instead, the managed object is effectively synthesized when there is a request on it, which for volatile objects happens much less often than creations and deletions. Serialized Forms ---------------- The serialized forms of Java DMK classes were not specified explicitly in previous versions. Because JSR 160 (JMX remoting) will include remote management, it is important for interoperability between different implementations that serialized forms be specified completely, and cleaned up where necessary. This has been done in the JMX specification, version 1.1, and is included in the Java DMK 5.0. See the paragraph on the Java property jmx.serial.form in the section "Backwards Compatibility" in Part II "Release and Version Issues". Support for Multihome Interfaces -------------------------------- Multihome interfaces are supported in the Java DMK 5.0. Connectors, adaptors and the discovery service have been enhanced to allow a user to select a host address. See "API Changes in This Release" in Part III "Product Notes". Other New Features ------------------ A simple design pattern is provided and implemented to delegate thread management in SNMP trap and inform dispatching to user code. This feature uses the following: - com.sun.jdmk.tasks.TaskServer interface, implemented by objects that are able to execute tasks. - com.sun.jdmk.tasks.Task interface, implemented by objects that can be executed by a TaskServer. - com.sun.jdmk.tasks.DaemonTaskServer class, implementing a task server that runs in its own thread. A new class, com.sun.jdmk.snmp.SnmpEventReportDispatcher has been created. It extends the javax.management.snmp.manager. SnmpEventReportDispatcher class and uses the Task and TaskServer interfaces to optimize receipt and dispatching of traps. ================================ II. Release and Version Issues ================================ JMX Specification Compatibility ------------------------------- See Part I "Enhancements and Major Changes in This Release". Operating Environments and Java Version Compatibility ----------------------------------------------------- The Java DMK version 5.0 is officially supported for development platforms under the following configuration: - Solaris 8 operating environment, update 7 (SPARC Platform Edition), with Java 2 SDK, v1.4.0. - Solaris 9 operating environment (SPARC Platform Edition), with Java 2 SDK, v1.4.0. - Windows 2000 operating environment, Service Pack 2 JDK 1.1.x versions are no longer provided. Backwards Compatibility ----------------------- Versions 5.0 and 4.2 of the Java DMK are communications-compatible: applications developed and running with version 4.2 can communicate with those developed with and running version 5.0. There is complete compatibility between agents using version 4.2 and managers using version 5.0. In the reverse case of an agent using 5.0 and a manager using 4.2, there is only a minor limitation with the connector heartbeat feature (see "Heartbeat Cross-Compatibility" and "HTTP and HTTPS Interoperability"). Java DMK 5.0 connectors are only interoperable with version 4.2 if a Java property jmx.serial.form has the value "1.0". It is not possible for a Java DMK 5.0 agent or manager to interoperate at the same time with both 4.2 and 5.0 managers or agents. Apart from this, 5.0 connectors interoperate with 4.2 connectors, regardless of which end is client or server. Due to major architectural changes, including the JMX compatibility, there is no communications-compatibility between version 5.0 of the Java DMK and versions 4.1, 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 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 DMK, 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 5.0 release are totally compatible with those generated by the 4.2 version, in terms of both binary and source compatibility. Therefore you do not need to regenerate MIBs. Files generated by the mibgen tool of the 5.0 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. Proxy MBeans generated using the proxygen tool provided with the 4.2 release are not compatible with the new 5.0 release, since their previous implementation relied on deprecated methods. These deprecated methods have been removed. These proxy MBeans must therefore be regenerated. SNMP API binary compatibility should be preserved between versions 4.2 and 5.0 of the Java DMK, for applications not using APIs declared as deprecated in version 4.2. See the section on "API Changes in This Release" in the part III "Product Notes". Regarding API source compatibility between versions 4.2 and 5.0 of the Java DMK, you should note that features that were declared as deprecated in the 4.2 version have been removed in 5.0. Furthermore, some interfaces have been extended. See the section on "API Changes in This Release" in Part III "Product Notes". Cross-Platform Compatibility ---------------------------- When product version compatibility and Java version compatibility are respected, the Java DMK offers full management compatibility across heterogeneous platforms. For example, a manager running on a SPARC server could manage a whole deployment of Windows 2000 PCs, controlling their availability and upgrading their Java-technology based software when needed. SNMPv3 Interoperability ----------------------- Java DMK 5.0 SNMPv3 implementation has been successfully tested with open source ucd-snmp-4.2.2. =================== III. Product Notes =================== API Changes in This Release (see Javadoc) --------------------------- The following API changes have been made in the Java DMK 5.0 compared with the 4.2 release: - The com.sun.jdmk.snmp.IPAcl.IPAcl interface is deprecated and replaced by the javax.management.snmp.InetAddressAcl interface. - The method processSnmpTrapV3(...) has been added to the interface javax.management.snmp.manager.SnmpTrapListener. It is called by SnmpEventReportDispatcher when an SNMPv2 trap PDU is received within an SNMPv3 message. Existing code that implements the SnmpTrapListener interface must be extended so that it implements the new methods too. - The method processSnmpInformV3(...) has been added to the interface javax.management.snmp.manager.SnmpInformListener. It is called by SnmpEventReportDispatcher when an inform request is received within an SNMPv3 message. Existing code that implements the SnmpInformListener interface must be extended so that it implements the new methods too. - The methods allocateUserData(...) and releaseUserData(...) have been added to the com.sun.jdmk.snmp.agent.SnmpUserDataFactory interface. - The methods decodeSnmpPdu(...) and encodeSnmpPdu(...) have been added to the javax.management.snmp.SnmpPduFactory interface. They replace the deprecated methods decodePdu(...) and encodePdu(...) respectively. - The following classes have each acquired an additional constructor that takes an extra parameter of type String to specify the local host address, used for receiving notifications when using the push mode: * com.sun.jdmk.comm.HttpConnectorClient * com.sun.jdmk.comm.HttpsConnectorClient * com.sun.jdmk.comm.RmiConnectorClient The new constructors replace deprecated constructors taking parameters of type InetAddress. - The following classes have each acquired an additional constructor that takes an extra parameter of type InetAddress to specify an InetAddress used to join or leave a multicast group. Previously this address was always the default local address: * com.sun.jdmk.discovery.DiscoveryClient * com.sun.jdmk.discovery.DiscoveryResponder * com.sun.jdmk.discovery.DiscoveryMonitor - A new constructor has been added to the class com.sun.jdmk.discovery.DiscoveryResponder enabling you to specify a local address (String) which is sent out in a response message to indicate which interface a client must use to connect to the MBean server. - The constructor with no parameters of class com.sun.jdmk.MBeanServerImpl has been removed. You should use the method MBeanServerFactory.createMBeanServer instead of referencing the MBeanServerImpl class. - Constructors for the class com.sun.jdmk.comm.SnmpAdaptorServer having IPAcl as parameter have been deprecated. New constructors based on the InetAddressAcl interface have been added. - The ACL file location has changed location from 4.2 to 5.0. In version 5.0, the ACL information is stored in a flat file and its default location is specified in the following order: 1. The value of the jdmk.acl.file property. 2. The return value of getEtcDir("conf" + File.separator + "jdmk.acl") in class com.sun.jdmk.defaults.DefaultPaths. The ACL file no longer requires the Java DMK JAR file to be in the default classpath, and no longer searches for files in the user's home directory as it formerly did if it could not find the Java DMK JAR file. - Changes linked to the fact that in JMX v1.1 an MBean is now dynamic when it extends a dynamic one. - The AuthInfo class is no longer serializable. See the Javadoc provided for further details. - In release 4.2, when a nonexistent file was passed to com.sun.jdmk.snmp.IPAcl.JdmkAcl, access control was not activated and the adaptor started. In release 5.0, if the file does not exist, an IllegalArgumentException is thrown. - In release 4.2, a badly formatted ACL file led to a very restrictive access control. No community string was accepted. In release 5.0, badly formatted InetAddressAcl and UserAcl files lead to an IllegalArgumentException. APIs Deprecated in This Release ------------------------------- Some API classes and interfaces have been designated as deprecated in this release. Refer to the Javadoc(TM) provided for more information. Removal of Features Deprecated in Version 4.2 --------------------------------------------- All features marked as deprecated in the Java Dynamic Management Kit 4.2 APIs have been removed from the 5.0 release. Therefore code that generated warnings about deprecated methods in version 4.2 will no longer compile in 5.0. SNMPv3 Security Configuration ----------------------------- USM security configuration is based on the jdmk.security text file. Persistence and updates are achieved by writing the configuration to this file. An InetAddressAcl file (jdmk.acl file) contains an access control list (ACL) group defining community and manager access rights and a trap group defining the community and hosts for sending traps. The user-based security model is based on the jdmk.uacl file. Full details of the security configuration are provided in the "Java Dynamic Management Kit 5.0 Tutorial", chapter 20 "Security Mechanisms in the SNMP Toolkit". This chapter also describes the agent example, which demonstrates how the security files are used. Optimization ------------ The following have been optimized in this release: - ObjectName parsing. - The com.sun.jdmk.snmp.SnmpEventReportDispatcher class which can be used to replace the javax.management.snmp.manager.SnmpEventReportDispatcher class when you need to tune performance. - The query() method of the RepositorySupport class. The query() method is called by the queryNames() and queryMBeans() methods of the MBeanServer. - HTTP communication speed. - An internal thread service, used to share and reuse threads, thus improving SnmpAdaptorServer classes and the timer service. - Monitors no longer create a new thread every sampling period, but reuse the same thread continually. Trace Mechanism --------------- The trace mechanism is now implemented by two classes, which replace the deprecated com.sun.jdmk.Trace class: - com.sun.jdmk.trace.Trace is used to send trace messages. - com.sun.jdmk.TraceManager provides methods for receiving trace and debug information. In this release, more output information is printed for the trace mechanism, as follows: - The name of a thread which is executing the method - The time stamp The following example shows the additional information: Example for version 5.0: ... (DefaultMBeanAccessor registerMBean Thread-1 18:02:48:826) ObjectName = DefaultDomain:type=SimpleStandard (Repository addMBean Thread-1 18:02:48:827) name=DefaultDomain:type=SimpleStandard ... Example for version 4.2: ... (DefaultMBeanAccessor registerMBean) ObjectName = DefaultDomain:type=SimpleStandard (Repository addMBean) name=DefaultDomain:type=SimpleStandard ... Change in Subnet Masks in SNMP template.acl ------------------------------------------- The subnet mask syntax using the character ! is no longer supported. Java DMK 5.0 supports the subnet mask prefix notation. See RFC 2373. Examples -------- The Java DMK 5.0 includes a set of examples designed to enhance your understanding of the software features. Many of these are new examples, or have been updated to demonstrate usage of new features. Most of the examples are described in detail in the "Java Dynamic Management Kit 5.0 Tutorial". Each example includes a detailed README file and well-commented code. The examples are located in the examples package (or component), which you can choose to install using the installation wizard or pkgadd command. The examples provided with the Java DMK 5.0 and their locations are as follows. In the paths given, the directories (folders) are installed directly under the main examples directory (or folder). New examples and examples updated for SNMPv3 are indicated with the prefix * in this list. - Base Agent: /BaseAgent/ - Cascading: /Cascading/ - Context: /Context/ - Discovery: /Discovery/ - Dynamic MBean: /DynamicMBean/ - Heartbeat: /HeartBeat/ - Jdmk Proxy MBeans: /JdmkProxyMBeans/ - *MBean Interceptor (new example): /MBeanInterceptor/ - MLet Agent: /MLetAgent/ - MLet Client: /MLetClient/ - Minimal Agent: /MinimalAgent/ - Model MBean: /ModelMBean/ - Monitor MBean: /MonitorMBean/ - Notification: /Notification/ - Notification 2: /Notification2/ - *Open MBean (new example): /OpenMBean/ - *Open MBean 2 (new example): /OpenMBean2/ - Queries: /Queries/ - Relation: /Relation/ - Simple Clients: /SimpleClients/ - *SNMP Agent (updated for SNMPv3): /Snmp/Agent/ - *SNMP Engine ID (new example): /Snmp/EngineID/ - *SNMP Inform (updated for SNMPv3): /Snmp/Inform/ - *SNMP Manager (updated for SNMPv3): /Snmp/Manager/ - *SNMP Master Agent (new example, replaces SNMP proxy example): /Snmp/MasterAgent/ - SNMP Row Status: /Snmp/RowStatus/ - SNMP User Data: /Snmp/UserData/ - SNMP USM MIB user creation: /Snmp/UsmMib/ - Solaris kstat: /SolarisKstat/ - Standard MBean: /StandardMBean/ Unsupported Contributions ------------------------- A set of tools, examples, and features based on the Java DMK 5.0 are provided as unsupported contributions. Sun Microsystems will not provide technical support for these software components. A README file provided with each contribution describes how to use the software. You can install the software by manually copying the files to your system. The contributions are located on the CD-ROM in the jdmk_5_0/contrib/ directory and are not installed by the installation procedures using either the installation wizard or the pkgadd command. The Java DMK 5.0 includes the following unsupported contributions: - Java Agent Manager (JAM) Software --------------------------------- The Java DMK 5.0 Java agent manager (JAM) software is a graphical user interface (GUI) that helps you develop, test and deploy the JMX-compatible management and monitoring facets of your Java and J2EE resources. The JAM software is located on the CD-ROM in the jdmk_5_0/contrib/jam directory, which also contains an HTML tutorial. - Cascading Implementation ------------------------ This contribution provides a new implementation of the cascading service over the Java DMK 5.0 MBean interceptors. This new implementation of the cascading service includes the following features: * Same Management Interface as the standard cascading agent service. * Enhanced scalability: The MBeanInterceptor forwards all requests to its related subagent. There is no longer any need to register one proxy per cascaded MBean. * Detection of Cascading Loops. * Built-in reconnection hooks, disabled by default (see CascadingAgent). * RestartableCascadingAgent which overrides the reconnection hooks and makes it possible to automatically reconnect with subagents that have failed and have been restarted. * RemoteMBeanInterceptor which wraps a RemoteMBeanServer. * Emission of ConnectionStateNotification which makes it possible to monitor the connection with the subagent (see CascadingAgent). * An example (see examples directory) that shows how to use the RestartableCascadingAgent. The cascading software is located on the CD-ROM in the jdmk_5_0/contrib/cascading directory. - Easy Manager ------------ The easy manager is a command line SNMP manager that enables you to make SNMPv1, SNMPv2, and SNMPv3 requests and receive traps and informs. The easy manager software is located on the CD-ROM in the jdmk_5_0/contrib/easymanager directory. - RFC 2573 Implementation ----------------------- This is an implementation of the proxy and notification applications defined in the SNMPv3 RFC 2573 "SNMP Applications". The proxy and notification application MIBs are also part of this contribution. The RFC 2573 implementation software is located on the CD-ROM in the jdmk_5_0/contrib/rfc2573 directory. ====================== IV. Known Limitations ====================== The following is a list of known restrictions in this release of the Java DMK 5.0 at the time this document was written (June 2002). Details of workarounds are given where possible. Dependency of the SUNWwbcou Package on the SUNWjsnmp Package ------------------------------------------------------------ This information is only relevant to users of the Solaris operating environment. You might already have on your system an instance of version 1.0 of the SUNWjsnmp package, provided with the Solaris operating environment since version 8. The Java DMK 5.0 software includes version 5.0 of the SUNWjsnmp package, which is a later version and which cannot coexist with version 1.0 of the package. Consequently, before installing the Java DMK 5.0 software, check whether the SUNWjsnmp package is present on your system, by typing: pkginfo -l SUNWjsnmp If an instance of the SUNWjsnmp package is present on your system, uninstall this package using the pkgrm command before installing the Java DMK 5.0. The SUNWwbcou WBEM services package, provided with the Solaris operating environment since version 8 update 5, has a dependency on the SUNWjsnmp package. This dependency is explicitly mentioned in version 8 update 5 and in version 9, but it is not explicitly mentioned in version 8 update 7. If the SUNWwbcou package is present on your system, do not remove the SUNWjsnmp package if you subsequently decide to uninstall the Java DMK 5.0. Before uninstalling the Java DMK 5.0 software, check whether the SUNWwbcou package is present on your system, by typing: pkginfo -l SUNWwbcou If the SUNWwbcou package is present on your system, uninstall the software using one of the following methods: - Choose a "Partial" uninstallation with the uninstallation wizard, and do not select the SUNWjsnmp package. - Use the pkgrm command but do not specify the SUNWjsnmp package. See the "Java Dynamic Management Kit 5.0 Installation Guide" for detailed descriptions of the software installation and removal procedures. SNMPv3 Protocol --------------- RFC 2575 (view-based access control model) is not fully supported in this release. RFC 2573 (applications) is not supported in this release. The following interpretation has been made of section (5) of USM 2574 RFC: The usmUserStorageType values supported are volatile (2) and nonVolatile (3). See Section I "Enhancements and Major Changes in This Release" for more information on SNMPv3. The following interpretation has been made of section (3.2.5) of USM 2574 RFC: USM will accept requests that contain a security level that is lower than that located in the agent configuration. If a user is configured with authentication and encryption, authenticated-only requests will be accepted. If a user is authenticated with authentication only, authenticated and encrypted requests will not be accepted. You must configure the access control model using the UserAcl to control users' access to MIBs based on the following security levels: - No authentication and no privacy (noAuthNoPriv). - Authentication only (authNoPriv). - Authentication and privacy (authPriv). Requests with unknown context names are ignored by the adaptor. This leads to a timeout on the manager side. To avoid this, always use known context names. SnmpPduFactory -------------- If you developed code using the SnmpPduFactory class in version 4.2, it will not work with the Java DMK 5.0 SnmpV3AdaptorServer class. It will work with the SnmpAdaptorServer class. See the SNMP agent example, located in the /Snmp/Agent directory, which demonstrates how to implement the SnmpPduFactory class. This example is described in detail in the "Java Dynamic Management Kit 5.0 Tutorial". HTTP and HTTPS Interoperability (Bug ID 4643795) ------------------------------- You might encounter an interoperability problem when running a Java DMK 5.0 agent on JDK 1.4 with a Java DMK 4.2 client on JDK 1.3.1_0, where i is between 1 and 3. The problem arises only when using the HTTP and HTTPS protocols. Agent exceptions are transmitted incorrectly to the remote client, which then receives a different exception from that expected. Connector Interoperability (Bug ID 4700315) -------------------------- The serial form of the class com.sun.jdmk.discovery.DiscoveryResponderNotification changed incompatibly between Java DMK versions 4.2 and 5.0. This means that if a 4.2 manager registers a remote listener on a DiscoveryMonitor in a 5.0 agent, or vice versa, it will not receive any notifications. Registering a listener on a local DiscoveryMonitor will work correctly, so the impact of this problem is minor. setAuthorizedListFile() Method (Bug ID 4697379) -------------------------------------- The setAuthorizedListFile() method of the classes JdmkAcl and JdmkUserAcl does not work as expected. You must call the rereadTheFile() method after calling this method. Using pkgchk on a newly installed SUNWjdrt package (Bug ID 4701815) -------------------------------------------------- When running the pkgchk command on a freshly installed SUNWjdrt package there is an error on the jdmkrt.jar file: % pkgchk SUNWjdrt ERROR: /opt/SUNWjdmk/jdmk5.0/lib/jdmkrt.jar permissions <0444> expected <0644> actual group name expected actual file size <814829> expected <807574> actual file cksum <64489> expected <45769> actual This is a known bug, which has no impact on the usability of the package. Javadoc "since" Tags (Bug ID 4702307) -------------------- The methods SnmpTrapListener.processSnmpTrapV3 and SnmpInformListener.processSnmpInformV3 are new in Java DMK 5.0 but are not marked as such in the Javadoc documentation. Also, the interface SnmpTrapListener is incorrectly marked "since Java DMK 5.0" when it is only its method processSnmpTrapV3 that is new. 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 has not 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. See the JAM contribution described in the "Unsupported Contributions" section of Part III "Product Notes". The JAM contribution lifts the restriction on types. Heartbeat Cross-Compatibility ----------------------------- When a manager application running with version 4.2 of the product is communicating with agents running version 5.0, the heartbeat mechanism might 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 can avoid this limitation 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 can connect and disconnect as many times as you want. If you would like to use the heartbeat functionality in this configuration, do not reconnect a connector client to a server. The heartbeat mechanism is fully functional during the first connection. If you need to reconnect, you should disconnect the connector client and instantiate a new connector client. HTTPS Heartbeat on Windows 2000 ------------------------------- The HTTPS connector client on the Windows 2000 platform might 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. M-Let with JDK 1.4 Software --------------------------- When using the m-let service with the JDK 1.4 software, in particular when calling one of the following methods: - getMBeansFromURL(java.lang.String url) - getMBeansFromURL(java.net.URL url) a javax.management.ServiceNotFoundException might be raised. This occurs because the JDK 1.4 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 releases of the Java DMK prior to 4.2, the SnmpVarBind status was handled differently, depending upon whether you were using SNMPv1 or SNMPv2. This is no longer the case with the Java DMK 4.2 and 5.0. The SnmpVarBind status handling has been modified to allow the user to perform status checking in the same way for both SNMPv1 and SNMPv2, although it might impact the Java code if you are using SNMPv2. Now, regardless of the SNMP version you use to send a request, the SnmpVarBind status, as given by the getValueStatus method, is independent of the SNMP version with which the request was sent. Therefore, you can compare the status with the following constants which are defined in the SnmpVarBind class: - stValueOk - stValueEndOfMibView - stValueNoSuchInstance - stValueNoSuchObject - stValueUnspecified ==================================== V. Documentation Errata and Addenda ==================================== 1) The "Java Dynamic Management Kit 5.0 Tutorial" covers most 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. 2) The "Java Dynamic Management Kit 5.0 Tutorial" should specify the following information in Chapter 18 "Creating an SNMP Agent": The operating system where your agent runs might already have an SNMP agent listening to the default SNMP port, 161. For instance, the Solaris operating environment has an agent called snmpdx that listens to this port. You have a number of choices in deploying your agent: - Have your agent listen on another port and be completely independent of the standard system agent. - If the standard system agent supports master agent functionality, you might be able to configure it so that your agent is a subagent. For instance, with Solaris snmpdx you can do this as described in the "Solaris Enterprise Agents 1.0 User Guide". To access this guide online, see: http://docs.sun.com/db/doc/816-1322/ - If you require functionality, such as SNMPv3 support, that is not available with your standard system agent, you might be able to configure your system so that the standard system agent runs on another port and your agent runs on the default port, 161. Using the Java DMK's master agent functionality, described in chapter 21, the standard system agent can be configured as a subagent of your agent. This means that a manager that previously communicated directly with the standard system agent can communicate with your agent without requiring any changes. 3) The "Java Dynamic Management Kit 5.0 Tools Reference" should specify the following information: The scripts for starting the mibgen tool and the proxygen tool use the JAVA_HOME environment variable to determine the JDK path. Therefore, even if you have the correct JDK 1.4 path in your PATH environment variable, this setting is overwritten by the JAVA_HOME variable. 4) The "Java Dynamic Management Kit 5.0 Installation Guide" should specify the following information in Chapter 3 "Installation on Other Platforms": When you have extracted the contents of the ZIP file as described in the procedure "To Install the Software From the ZIP File", you might need to edit the install.path file. You must edit this file if you want to use the following Java DMK features and you have not set the corresponding Java properties: - The methods of the class com.sun.jdmk.defaults.DefaultPaths. - SNMP security to access the jdmk.security file, the jdmk.acl file and the jdmk.uacl file. If the following Java properties are set, the defaults will not be used: * jdmk.security.file * jdmk.acl.file * jdmk.uacl.file - The mibgen tool, to access the mibcore file. If the Java property mibcore.file is set, the default will not be used. - M-let service, to determine the path where the libraries are located. If the Java property jmx.mlet.library.dir is set, the default will not be used. To Edit the install.path File ----------------------------- a) Extract the com/sun/jdmk/defaults/install.path file. To do this, type the following command at the command line: jar xvf jdmkrt.jar com/sun/jdmk/defaults/install.path b) Open the install.path file in a text editor. c) Replace INSTALL_PATH_XXX with the absolute path of the directory containing the lib directory. d) Save the install.path file. e) Update the jdmkrt.jar file. To do this, type the following command at the command line: jar uvf jdmkrt.jar com/sun/jdmk/defaults/install.path 5) When you install the product documentation on a Windows 2000 operating environment, you might encounter difficulties reading the jmx_instr_agent.pdf file you have installed. This file should contain the specification document "Java Management Extensions Instrumentation and Agent Specification, v1.1" (Maintenance Release, March 2002). If you are unable to read the installed version of this file, use the version provided on the CD-ROM at jdmk_5_0\docs\jmx_instr_agent.pdf. We want to know what you think about the Java Dynamic Management Kit 5.0 software and documentation set. Please send your comments, feedback, and suggestions to your customer support team.