Main Index  Release Notes  TMX4J Base  TMX4J Extensions  FAQ 

 

TMX4J Frequently Asked Questions

General Questions

What is JMX?

The Java™ Management Extensions (also called the JMX specification) define an architecture, the design patterns, the APIs, and the services for application and network management in the Java programming language.

What is TMX4J?

TMX4J is a Tivoli clean room implementation based on the JMX (Java Management Extensions) Specification v1.0

What is the base implementation?

The base implementation includes all the java packages necessary to instrument a JMX-compliant application. These are found in the jmxc.jar and the jmxx.jar files.

What is the extension implementation?

The extension implementation includes useful additional tools to manipulate and communicate with the TMX4J Agent, such as the Unix daemon/NT Service, the HTTP Adaptor, the RMI Connector, some sample Agents and sample MBeans.

What is an MBean?

An MBean (or Managed Bean) is a Java™ object that implements a specific interface and conforms to certain design patterns. These requirements formalize the representation of the resource’s management interface in the MBean. The management interface of a resource is the set of all necessary information and controls that a management application needs to operate on the resource. MBeans are either standard or dynamic. Standard MBeans are Java objects that conform to certain design patterns derived from the JavaBeans™ component model. Dynamic MBeans conform to a specific interface that offers more flexibility at run-time.

The jmxx.jar file distributed with TMX4J includes the VerifyMBeanCompliance tool to test if a Java class is a JMX-compliant MBean. If the class is an MBean the tool determines its type (standard or dynamic) and in the case of a standard MBean it displays all information about the exposed attributes and operations. In order to use this tool you have to type the following command:

java com.tivoli.jmx.tools.mbeanvalidator.VerifyMBeanCompliance java_class_name

Is the TMX4J implementation thread safe?

Yes, it is. And there is also an internal mechanism that forbids the deregistration of an MBean when another thread is executing one of its methods exposed for management.

How does the Bootstrap Service work?

The tmx4j MBeanServer automatically loads the Bootstrap Service MBean, whenever you call one of the MBeanServerFactory createMBeanServer methods. The BootstrapService will look for a URL address specified in your jmx.properties file, under the key BootstrapURL.

If you choose not to use this Service, the MBean will be registered anyway with the MBeanServer, and will log a warning on creation. Bootstrap failures of any kind will NOT stop the successful creation of the MBeanServer.

How do I specify the Bootstrap list?

The BootstrapURL must be a URL reference to a file, http or ftp address, where you have a list of MBeans to load. This list must be in the syntax specified by the example bootstrap.properties file, found in the tmx4j/ext/lib directory. The list includes the classname, objectname, and an optional list of startup parameters and their types. See the example bootstrap.properties file for guidelines on how to format the startup arguments. Do not forget to include both the .properties file and the MBeans on your classpath.

Where can I find the log files? How can I configure the logging information?

The default application log file name is Tmx4j_<number>.log. To modify the name of the log file(s) or define the size and number of log files you must modify the properties values in the jmx.properties file. You can control the number of messages logged to the log file or disable the logging too. See comments included in jmx.properties to get more information about message log configuration.

If you are using the TMX4J Sample Agent, the log can be found in the following directories:

Unix: The directory in which the log is created is determined by the EXECUTE_DIR environment variable (set in the jmxd.sh script).

NT: The log file is created in the c:\winnt\system32 directory.

What happens to a deregistered MBean no longer reachable through other references when it is set as a listener in a NotificationBroadcasterSupport instance?

It will never be garbage collected.

Why do I have to specify the type name of the parameters for an mbeanserver invoke?

It is needed to uniquely identify the method to be invoked. For instance, the RequiredModelMBean has a method named setModelMBeanInfo, if you try to invoke it through the MBean server, you will have to specify as parameter type the interface ModelMBeanInfo implemented by the ModelMBeanInfoSupport as shown below:

ModelMBeanInfoSupport mmbis = ...//creation  mBeanServer.invoke(modelMBeanName, "setModelMBeanInfo", new Object[] {mmbis}, new String[] {ModelMBeanInfo.class.getName()});

In fact, setModelMBeanInfo declares the following signature:


    void setModelMBeanInfo(ModelMBeanInfo mbi);
  

Is it possible to call the methods declared by the Dynamic interface through the invoke method of the MBeanServer?

No, it is not possible unless the developer of the Dynamic MBean has implemented his own invoke in order to support this feature. For instance, if we try to call the getMBeanInfo through the invoke as shown below:


    mBeanServer.invoke(mBeanObjectName, "getMBeanInfo", new Object[0], new String[0]);
  

It will throw java.lang.IllegalArgumentException. In fact, the getMBeanInfo method should be called through the getMBeanInfo of the MBeanServer:


    mBeanServer.getMBeanInfo(mBeanObjectName);
  

What is the correct format for an ObjectName?

The syntax of the ObjectName is:

[domainName]:property=value[,property=value]*

The domain name may be omitted to designate the default domain.

What pattern matching syntax can I use to query a range of MBeans?

The ObjectName matching syntax is consistent with standard file globing, in other words:

* matches any character sequence, including an empty one

? matches any one single character

In addition on the property keys the following patterns can be used:

[a-n] matches a character range from a to n

[abc] matches one of the characters a,b or c

[!n] negates the character n

What do I need to set my Classpath to?

The classpath must include the jmxc.jar, jmxx.jar and the jmx.properties file (base version), as well as the jmxext.jar, adaptor.properties and bootstrap.properties files (extension version). For the location of these files refer to the README.html file.

What is the HTTP Adaptor port?

The default adaptor port is 6969. This can be changed in the adaptor.properties file. Note that after changing this value you will need to stop and restart the Adaptor.

How do I use the provided RMI Connector?

The RMI Connector Server binds to the location specified by the "connection" key of its ObjectName. For example if it is created with the ObjectName:

"my-domain:connection=//localhost/MBeanServerConnection"

it binds to "//localhost/MBeanServerConnection". RMI clients that want to connect should call: java.rmi.Naming.lookup() with the appropriate location as a parameter. Obviously rmid must be running for this to work as well. Once bound to the server clients make calls to the methods defined by the MBeanServerConnection interface.


Monitor Questions

A counter monitor is a monitor that verifies whether a numeral attribute (Byte, Short, Integer, Long) reaches or exceeds a threshold value. Optionally, the threshold value is incremented by an offset every time the comparison level is reached. In case the attribute wraps around, a modulus attribute is used to represent the highest value that the monitored attribute can reach. The listener can receive a notification when the threshold is reached. The counter monitor can also work in difference mode. In this case the difference between two subsequent observations is compared against the threshold. In case the difference mode is enabled, at starting time a notification can be sent only after two subsequent observations. During this period the derived gauge (DG) is an Integer(0);

The Counter Monitor observed attribute must be always positive or null and that can be only incremented. To describe the algorithm, let us use the following shortcuts:

DG = Current Derived Gauge.

PDG = Previous Derived Gauge. 

CTH = Threshold.

PTH = Previous Threshold.

OF = Offset.

OV = Observed Value

Modulus = Modulus.

 A Counter Monitor sends a notification of type jmx.monitor.error.runtime in the following situations:

   ·  The observed value is negative (OV<0);

The observed value cannot negative. The observed value is not a Counter.

·  The derived gauge is negative (DG<0);

The DG computed with the modulus is negative, this happens when the modulus is not set properly or the observed value does not behave as a counter (strictly increasing).

·  The derived gauge is greater than the Modulus;(DG>Modulus)

The modulus is not set properly. In difference mode this happens if the observed values change too quickly. In this case, either the modulus or the GP are not set properly.

 

Note that the monitor keeps working after these notifications. 

When the user does not set the Modulus, it is set to the maximum allowed value for that specific primitive type wrapper. For instance, for BYTE variables the Modulus is set to Byte. MAX_VALUE.

The Counter Monitor algorithm can be outlined in the following way:

·  Observes the value and updates the derived gauge. In case the difference mode is active, the derived gauge is the number of increments between two subsequent observations.

·  Sends a notification if the threshold has been exceeded. A notification is sent when:

a.         (CTH > PTH) && DG Î [CTH, Modulus]È[0,PDG) ) ||

b.        ((CTH <= PTH) && ( ((PDG>=CTH) && DG Î [CTH, PDG) ) ||  ((PDG<CTH) && DG Î [CTH, Modulus]È[0,PDG)))

The case described in (a) occurs when the derived gauge is between the threshold and the modulus or below the previous derived gauge. The second case occurs when the derived gauge has rolled over.

The case described in (b1) occurs when the threshold has rolled over during the previous observation because the PTH + OFFSET was greater than the modulus.

The case described in (b2) occurs when the observed value at the time t has rolled over. Note that the condition PDG<CTH is strict because this situation occurs only if the threshold value has rolled over, therefore the threshold will be always greater than the derived gauge.

·  Updates the Threshold. If (DG>PDG), the CTH becomes greater than DG unless it exceeds the modulus. In this case CTH is set to the initial threshold. In case the (DG<PDG), the CTH becomes a value greater than the DG gauge starting from the initial threshold (ITH). 

Note that in case two or more successive observations of the observed attribute have the same value, the counter monitor won't send a notification and it won't compute the new threshold.
 

How does the gauge monitor algorithm work?

The purpose of a gauge monitor is to observe an attribute of an mbean. It sends a notification when the current derived gauge crosses one of two user-defined thresholds (named high threshold and low threshold) according to a hysteresis mechanism. The hysteresis mechanism does not allow sending a notification when a threshold is crossed unless the opposite threshold had been crossed previously. A gauge monitor can be configured to work in difference mode or not. In case the difference mode is not enabled, the derived gauge consists of the observed value, while, in case the difference mode is enabled, the derived gauge consists of the difference between two subsequent observations. 

When a gauge monitor is started, it has to wait two subsequent derived gauge values before beginning the actual monitoring activity. This means that three observations are required in difference mode and only two in the other case. A complete description of the notification policy can be divided in two parts, according to the thresholds values:

1.      In case the thresholds are different, the notifications are sent according to the following rules: 

a. All the observations are ignored until there are two subsequent observations with an ascending slope and the last observed gauge is equal or higher than the high threshold value. 

b.All the observations are ignored until there are two subsequent observations with a descending slope and the last observed gauge is equal or lower than the low threshold value. 

c. The first two observations have the same value and they are equal or greater than the high threshold value. 

d.The first two observations have the same value and they are equal or lower than the low threshold value. 

2.      In case the thresholds are equal, the notifications are sent according to the following rules: 

a. All the observations are ignored until two subsequent observations with a descending slope and the last one is equal or lower than the threshold. 

b.All the observations are ignored until two subsequent observations with an ascending slope and the last one is equal or greater than the threshold. 

c. The first observation is equal to the second one and they are both greater than the threshold. 

d.The first observation is equal to the second one and they are both lower than the threshold.

Notifications are not sent when: 

e. The first two observations are equal to the threshold. 

Note that a slope is determined by the difference between two subsequent derived gauges.

What happens when there are several monitors with the same Granularity Period (GP) observing attributes at (nearly) the same moment?

A little delay may occur in the observation activity. In fact, the observation mechanism is implemented with a consumer thread that manages a priority queue containing all the scheduled observations to be executed.Therefore, if there are several observations scheduled at the same time, except for the first one, all the others will be delayed.This scenario becomes more likely when a JVM contains several monitors with the same granularity period (GP) or GPs that are multiples of each other as long as these monitors are started at the same time or at intervals multiple of the GP.

What happens when the observation takes too long in a Monitor?

If the observation execution takes more time than its GP, the subsequent observation will be executed at the closest “tick” multiple of GP. This means that one or more scheduled observations might be missed if the getAttribute invocation is slower than expected. Note that only the current monitor will be affected since there is thread pool that manages the scheduling and observation activity for all the active monitors.

How can I configure the monitors thread pool?

You should add the following keys: Monitor_Max  = <min_value>, Monitor_Min  = <max_value>, Monitor_Growth = <growth_value> to the jmx.properties file. The valid values for the Monitor_Min, Monitor_Max and Monitor_ Growth keys are shown below:

Set

Action

Cache

Target Resource

>=0

>0

>0

max - min >= growth

>0

>0

=0

max == min

=0

=0

=0

legal

>0

=0

>0

Illegal

=0

>0

=0

Illegal

=0

=0

>0

Illegal

>0

=0

=0

Illegal

 

In case the jmx.properties file does not contain any of Monitor thread pool keys, the default values are applied. The default values for the monitor thread pool keys are: Monitor_Max = 20, Monitor_Min=1, Monitor_Growth=1.


Timer Questions

Can I add a notification to the Timer while it’s stopped?

Yes, it’s possible to add notifications to the Timer while it’s not running. If some of these notifications expire while the Timer is not active, they are not sent immediately. Once the Timer is started, all the expired Notifications are sent (the periodic ones are sent as many times as they are expired during Timer inactivity) if the sendPastNotifications flag is set to true.

Should I remove a notification that has already been sent?

No, this operation is performed automatically.

Should I remove a listener that I know is no longer interested in any notification?

Yes, the Timer is not able to understand if a listener is a 'zombie', so, in order to improve the performance, all not used listeners should be manually removed.

How can I pass an ObjectName to the Timer?

The method preRegister allows you to pass an ObjectName to the Timer. It’s mandatory to supply an ObjectName for the Timer.

Can I register multiple Timers?

Yes, multiple Timers can be registered in the same Agent, specifying different ObjectNames.


Model Questions

Is it possible to call the methods of the ModelMBean itself through the MbeanServer “invoke” method?

Yes, it is. The programmer must be careful after the RequiredModelMBean instantiation. It has to get the default ModelMBeanInfo and create a new one that contains the metadata objects for the managed resource together with those created by the RequiredModelMBean at instantiation time.

The setModelMBeanInfo completely replaces the current ModelMBeanInfo instance.

Is it possible to use target objects with overloaded methods in the RequiredModelMBean?

Yes, it is possible with some precautions since there is a flaw in the specification. In fact, there is no way to have different descriptors for overloaded methods since a descriptor has only a method name and nothing that describes the signature of the method. Therefore, the setDescriptor and setDescriptors methods of the ModelMBeanInfoSupport cannot substitute properly the descriptor of two homonymous operations with different parameters. The first operation met during the traversal is used to substitute the descriptor.

A programmer can use overloaded methods as long as the operations are created with their descriptors and used to instantiate a ModelMBeanInfoSupport. This instance is used to set the RequiredModelMBean object.

Can I use two instances of the same class as target objects in the RequiredModelMBean?

No, it is not possible. This is a flaw in the specification. There is no way to use two different instances of class as target objects in the descriptors since the operations with different target objects can be distinguished only using a fully qualified name that includes the class name.See the RequiredModelMBean.invoke for further details.

Is persistence supported by the TMX4J implementation of the RequiredModelMBean?

No, it isn't. Persistence is not a mandatory feature according to the final Jmx specification (July 2000). The current implementation throws a RuntimeOperationsException that wraps an UnsupportedOperationException for the store and load methods.

Does the DescriptorSupport class support the XML initialization?

No, it doesn't since the final Jmx specification (July 2000) does not specify a DTD for the XML String.

What happens when I try to set a read-only attribute?

Only the internal cache for that attribute will be set. Nothing happens to the managed resource or the target object. Note that an exception will be thrown.

Is it possible to change the ModelMBeanInfo when a RequiredModelMBean instance is registered?

The JMX specification states that it is not possible; nevertheless the current implementation does not have any means to stop a programmer doing this change on the fly since the RequiredModelMBean does not implement the MbeanRegistration interface. Side effects in case of concurrent access are possible.

How does the DescriptorSupport class manage field names and values?

The DescriptorSupport is case sensitive on field values while it is NOT case sensitive on field names for "gets" and "puts". Moreover, the DescriptorSupport class does not change the case of field names. In fact, all known field names, such as PersistPolicy, cannot be changed. Whatever the names the user chooses, they will have forever their "canonical" form as specified in the JMX documentation. The field names not known in advance (user defined field names) will have the case used the first time the pair key/value was set in the DescriptorSupport instance.

How does the notification mechanism work?

The TMX implementation manages listeners for AttributeChangeNotifications and Generic Notifications as two divided groups. An Exception is thrown if an AttributeChangeNotificationFilter instance is given in input to addNotificationListener.

1.      If a listener is registered only for Generic Notifications, only removeNotificationListeners can remove it.

2.      If a listener is registered for Generic Notifications and AttributeChangeNotifications, removeNotificationListeners can only remove the listener from the first group (Generic Notifications).

3.      If a listener is registered for Generic Notifications and AttributeChangeNotifications, removeAttributeChangeNotificationListener removes only from the second group (AttributeChangeNotifications).

4.      If a listener is registered only for AttributeChangeNotifications, removeNotificationListeners does NOT remove it.Only removeAttributeChangeNotificationListener can remove it.

5.      sendNotification sends the notification specified only to listeners added throughaddNotificationListener.

6.      sendAttributeChangeNotification sends the notification specified only to listeners added throughaddAddAttributeChangeNotificationListener.

How does the staleness mechanism work?

Below is described the behavior of the caching mechanism, where:

TS = Time Stamp 

CTL = Currency Time Limit

MR = Managed Resource

TG = Target Object

VC = Value in Cache

VR = Value Read from the MR or retuned by an invoke on the MR

VW = Value to be Written

The staleness check verifies whether the TS +CTL <= Invocation Time or not.  
 

 

Get/Invoke

Action

Cache

Returns

TS == NULL

CTL>0

Get/Invoke on the MR

TS, VR

VR from MR

CTL =0

Get/Ivoke on the MR or TG 

--

VR from MR

(CTL = -1)           &&                      (CV !=Null)

Get/Ivoke on the MR or TG

TS, VR

VR from MR

TS != NULL

CTL >0

Staleness check, if VC is stale, execute get/invoke

TS, VR

If stale à CV, otherwise à VR

CTL =0

Get/Ivoke on the MR or TG

--

VR

CTL = -1

--

--

CV

 

Set

Action

Cache

Target Resource

CTL > 0

Sets the VW on the MR

TS, VW

Writes VW

CTL = 0

Sets the VW on the MR

--

Writes VW

CTL < 0

Sets the VW on the MR

TS, VW

Writes VW


Relation Questions

Does the JMX relation model guarantees inter- relation checks?

No, the JMX relation model only guarantees that an MBean satisfied its designed role, it does not allow a user to define how many relations an MBean may appear in. 

Can an MBean be a role value and a relation at the same time in the same relation service?

Yes, it can. The JMX relation model allows defining nested relations.

When a relation, either external or internal, is removed from the relation service, the MBeans defined as roles only in that relations are deregistered from the MBean server?

No, these MBeans continue to be registered in the MBean Server. You can implement this behavior defining, for instance, these MBeans as listeners for the notifications sent from the Relations service: when they receive the notification that the relation, in which they are roles, has been removed, they can deregister themselves from the MBean server.

How can I implement an External relation?

An external relation is a class instance that implements the interface Relation added to the relation service. You can use the implementation provided in the relation package named RelationSupport or you can extend or delegate to this class or implement the Relation interface itself.


MLet Questions

What is the MLet service?

The MLet service is useful to load MBeans classes and resources inside an MBean Server's JVM from a remote host, and register the MBeans in a single action. With the provided loadMBeansFromURL() methods, you can make the MLet service parse a text XML-like document hosted on a remote Web Server, in which you specify, for each MBean you want to be registered, its class, path to the JAR file that contains the classes and optionally ObjectName and parameters to the MBean constructor. The JAR files will be added to the MLet search path, and can be used later to retrieve classes or resources needed by the MBeans loaded with this service, or to register other MBeans which classes are stored in one of them.

Can I use any type of class when registering MBeans with an MLet text file?

Yes, you can use your own classes for both the MBean and the parameters to the MBean's constructor. The only restriction is that the parameters' classes must have a String constructor.

Can I register serialized objects as MBeans, using the MLet service?

Yes, you can specify a .SER file as code source for the MBean you want to register, inside one of the MLet text file tags.

Do I need to have a Web Server in order to use the MLet service?

No, you can also specify an URL pointing to a local file, when registering MBeans with addMBeansFromURL().

Is the MLet text file XML compliant?

No, it has an XML-like syntax, but you don't need a super level tag, and you shouldn't put the fields' arguments in double quotes (except for the ARCHIVE tag's arguments). See the javadoc for the MLet class for details on the syntax.

What is the relationship between the MLet service and the DefaultLoaderRepository?

The DefaultLoaderRepository stores references to every MBean that is registered inside the MBeanServer that is also a ClassLoader. Thus, every MLet MBean is also referenced by the DefaultLoaderRepository and will be queried to load an MBean's class if the class is not found by other means.


Jar Installer Questions

What's the purpose of the JarInstallerMBean?

The JarInstallerMBean allows to create JMX agents that can use MBeans bundled in jar files deployed at run time.


 
Main Index  Release Notes  TMX4J Base  TMX4J Extensions  FAQ 

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
 
File Last Updated: 11/21/2001