4.6 Behavior of the Model MBean

Model MBeans provide support for some common MBean requirements ”caching, persistence, logging ”and a host of miscellaneous other services. This section describes the processing that model MBeans perform in these services. Remember, because RequiredModelMBean is an actual concrete class (and you have the source for it), you can extend it and override its behavior.

4.6.1 Caching

Caching is supported for both attribute values and operation responses. In general, if the data requested is current, then the model MBean returns the cached value and does not retrieve the value from or invoke the operation on the managed resource. The value is cached in the value descriptor field of ModelMBeanAttributeInfo or the lastReturnedValue field of ModelMBeanOperationInfo . Caching policy is defined by two descriptor fields: currencyTimeLimit and lastUpdatedTimeStamp . This is the algorithm for caching; it is relatively straightforward:

 if (currencyPeriod < 0)  {  /* if currencyTimeLimit is -1, then value is always current */   returnCachedValue = true;   resetValue = false; } else if (currencyPeriod == 0) {  /* if currencyTimeLimit is 0, then value is never current */   returnCachedValue = false;   resetValue = true; } else {  /* if now < currencyTimeLimit + LastUpdateTimeStamp */   String tStamp = (String)       descr.getFieldValue("lastUpdatedTimeStamp");   if (tStamp == null)   {     tStamp = "0";   }   long lastTime = (new Long(tStamp)).longValue();   long now = (new Date()).getTime();   if (now < (lastTime + currencyPeriod))   {     returnCachedValue = true;     resetValue = false;   } else   { /* value is expired */     returnCachedValue = false;     resetValue = true;   } } if (resetValue == true)   { /* value is not current, so remove it */     descr.setField("lastUpdatedTimeStamp", "0");     descr.setField("value", null);     response = null;   } If (returnCachedValue == true) {   response = descr.getFieldValue("value"); } else {   response = getAttribute();   descr.setField("lastUpdatedTimeStamp", now);   descr.setField("value", response); } return response; 

For attributes, if getAttribute() is called for an attribute with a stale value (or no value), then the getMethod defined in the attribute's descriptor will be invoked and the returned value will be recorded in value for the attribute, and the lastUpdatedTimeStamp field will set to the current time. The requester will be handed the new value. If no getMethod descriptor field is defined and the value field in the attribute descriptor is not set, then the value in the default descriptor field from the attribute's descriptor will be returned. Note that the cached value is set lazily; that is, it is not updated just because it is stale; someone must ask for it to trigger the update. Here is an example of caching descriptor fields for an attribute:

 "getMethod=getMyOwnAttribute"  "currencyTimeLimit=30" "lastUpdatedTimeStamp=03302002120905003" "value=highspeed" 

Similarly for operations, if an invoke() method is executed for an operation with a stale value (or no value) set in the lastReturnedValue field of the descriptor, then the invoke() method is executed for the operation and the returned value will be recorded in the lastReturnedValue field for the operation. Likewise, lastUpdatedTimeStamp will be set to the current time. The requester will be handed the new value. This cached value is also maintained lazily:

 "name=getRateOfSpeed"  "currencyTimeLimit=30" "lastUpdatedTimeStamp=03302002120905003" "lastReturnedValue=30mph" 

The currencyTimeLimit descriptor field may be in the model MBean's descriptor. When currencyTimeLimit is set here, it applies to all attributes and operations. If currencyTimeLimit is not defined, then the default is to do no caching. We can override the model MBean's default policy by defining it in the attribute or operations descriptor. As in the preceding examples, currencyTimeLimit is set to the number of seconds that a cached value is current. If currencyTimeLimit is set to :

 "currencyTimeLimit=0" 

then no caching is performed and the value is retrieved or operation invoked for every request.

If currencyTimeLimit is set to “ 1 :

 "currencyTimeLimit=-1" 

then the value is never stale. This is appropriate for static information or information that the managed resource populates in the model MBean. These types of managed resources may not be able to support or tolerate interruptions.

4.6.2 Values and Validation

The attribute descriptor contains three fields that govern the attribute's value outside of the caching algorithm: value , default , and legalValues . The value field is set by a setAttribute() operation and by caching support. It can be set statically and not updated from a managed resource, or it can be set on every iteration of getAttribute() . The default field defines the default value to be returned on getAttribute() for this attribute if there is no current data in the value field and a value cannot be retrieved from the managed resource. The legalValues field defines an array of values that are legal for the attribute. This field was meant to be a hint to a generated console or model MBean user. These values are not enforced by the model MBean or the descriptor. It is up to the model MBean user to consult and use them. Likewise it is up to the console developer to use legalValues appropriately.

 "defaultValue=True"  "legalValues=True,False" 

4.6.3 Delegation

Model MBeans delegate getAttribute() and setAttribute() method calls, as well as operations, to your managed resource. In every case the method invoked on your managed resources can be any method with any signature. The attribute descriptor contains a getMethod field and a setMethod field. These fields contain the names of the operations (in the same ModelMBeanInfo instance) that are to be executed to satisfy the get or the set. The operation's ModelMBeanOperationInfo instance defines the method signatures to be invoked on the managed resource. The managed resource is set for an entire model MBean with the setManagedResource() method on the model MBean itself.

The interesting thing here is that the operation descriptor allows the definition of its own target object. The targetObject descriptor field overrides setManagedResource() for just that operation. The override causes the MBean to send the invoke() command to a new object instance, perhaps even a different class of object. This is a very powerful feature of model MBeans and allows a great deal of flexibility for defining model MBeans for existing applications.

Figure 4.3 shows an MBean with its management interface and how attributes delegate to operations and operations delegate to methods on different target objects.

Figure 4.3. Operation Delegation to Target Objects

During initialization of the MBean itself, we would use a dashboard object as the default target for all methods:

 setManagedObject(dashboard) 

On the attribute descriptor for Rate , we would have

 "name=Rate"  "getMethod=getRateOfSpeed" 

Then on the operation descriptor for getRateOfSpeed , we would see

 "name=getRateOfSpeed"  "targetObject=" + mphGauge "targetObjectType=ObjectReference" 

This means that whenever the value of the Rate attribute is requested, the model MBean will invoke the mphGauge.getRateOfSpeed() method.

Now, the targetObjectType descriptor field identifies what type of reference the targetObject field's value is. The targetObjectType field may be set to ObjectReference , IOR , EJBHandle , or RMIReference . It may be set to other values as well, as long as the model MBean implementation recognizes the type and can deal with the reference appropriately. The JMX reference implementation supports only ObjectReference , which means that the reference in targetObject must be a local one. However, you can see that it was designed to work with remote objects as well.

4.6.4 Persistence

Model MBeans are responsible for persisting themselves . Persistence policy can be defined in the model MBean's descriptor and overridden in the attribute's descriptor. If a model MBean supports persistence, then some or all of the attributes may be persisted . This is important if you have highly volatile attributes (like counters) that have no meaning when they are saved. Using selective persistence, you can avoid the overhead of saving unstable, unusable data, like currentThreadPoolSize or currentSessionCount . Persistence is useful when the attributes that are persisted may be used to prime the next instantiation of the application or its model MBeans. For example, configuration attributes like traceState or long-running counters like totalNumberOfInvocationsOfApplicationInJuly would be good candidates for persistence. Persistence policy is defined by four descriptor fields: persistName , persistLocation , persistPolicy , and persistPeriod .

The persistName and persistLocation descriptor fields are defined only in the MBean-level descriptor. The persistName field defines the name of the model MBean in the persistence medium. If file persistence is being used, this is the file name. If database persistence is being used, the name is the primary key for the record. The persistLocation field defines where the model MBean is persisted. For file-based persistence this is the fully qualified directory. For database-based persistence this is the database name.

The persistence policy descriptor field, persistPolicy , can be set in the model MBean descriptor or attribute descriptor. It may be set to one of four policies:

1. persistPolicy=Never to switch persistence off

2. persistPolicy=OnTimer to force persistence at checkpoint intervals

3. persistPolicy=OnUpdate to allow persistence whenever the model MBean is updated

4. persistPolicy=NoMoreOftenThan to throttle the update persistence so that it does not write out the information any more frequently than a certain interval

If policies OnTimer or NoMoreOftenThan are defined, then the interval must be defined in the persistPeriod descriptor field. If the value of persistPolicy is not OnTimer or NoMoreOftenThan , then the persistPeriod field is ignored. The following combinations are valid in any MBean descriptor or attribute descriptor:

 "persistPolicy=Never"  "persistPolicy=OnTimer" "persistPeriod=180" "persistPolicy=OnUpdate" "persistPolicy=NoMoreOftenThan" "persistPeriod=10" 

When persistence policy is defined in the MBean descriptor, the directory and file names (or database and key, depending on the implementation) for the MBean are required. In such cases the descriptor would contain the following:

 "persistPolicy=OnTimer"  "persistPeriod=180" "persistName=MBean_File_Name" "persistLocation=MBean_Directory_Name" 

The algorithm that the model MBean uses is predictable. Whenever a model MBean detects that an attribute has been updated, or when a checkpoint time has been reached, it will invoke its own store() method. The model MBean store() method must determine where the data should reside and store it there appropriately. If, for example, the model MBean were implemented as an EJBObject instance with container-managed persistence, the store() method might do nothing, instead relying on the EJB container to provide the persistence on transaction boundaries. If the model MBean is implemented as an EJBObject instance through bean-managed persistence, the store() method might be responsible for writing the data to the appropriate data store.

The model MBean's load() method is invoked when a model MBean is being constructed and is set to prime itself from the saved data. Later in this chapter there is an example of how to override the model MBean's load() and store() methods to use XML-formatted files.

The MBeanServer's persistence setting applies to all of its model MBeans unless a model MBean defines overriding policies.

4.6.5 Logging

The descriptors that are used for setting logging policy are log and logFile . Logging policy can be set in the model MBean's descriptor to define default policy for all notifications in the model MBean. The log descriptor field is a Boolean value set to T ( true ) or F (false) . If the field is set to T , then the logFile descriptor field must be set to a valid, fully qualified file name (including the drive if appropriate) in the system. If the file does not exist, then one is created. If log is set to T and logFile is not set, no logging will occur. The default logging policy, if log is not specified, is F , or no logging. The default logging policy can be overridden by the logging policy of any notification's descriptor. Different notifications can be directed to different log files:

 "log=T",  "logFile=jmx.log" 

These descriptor fields on the MBean or notification descriptors will log the notification to the jmx.log file. If the descriptor were

 "log=F",  "logFile=jmx.log" 

then the notification would not be logged to any file, even if one were defined. The logFile descriptor would be ignored.

4.6.6 Miscellaneous Descriptors

4.6.6.1 Presentation String

The presentation descriptor field was intended to hold XML fragments that describe how to display the model MBean, attribute, operation, or notification. This information is useful to a generic or third-party console only if this XML fragment is standardized to some degree. This standardization, or agreement on what the important elements were, was not done for the first release of the JMX specification. However, the presentation field can still be very useful for building specific management systems for applications. Some information that we thought would be in this string was a GIF or a BMP file name for a small or large icon. If it were a configuration field, it might contain information on whether a list box, radio dial, range, or text box should be used to set the v alue. Here is an example of a presentation string that associates a GIF file with an attribute:

 "presentation=tooFast.gif" 

4.6.6.2 Visibility

Because JMX was intended to support both third-party, enterprise class management systems and application-specific management systems, it quickly became obvious that the amount of information an enterprise manager wants to display could be much less in volume and much coarser grained than the information displayed and managed by an application-specific management system. Even within application-specific management systems, in order to support the goal for allowing console generation for applications, some rating was needed about the granularity of this information.

This rating was used to decide whether to put the attribute or operation information on the "first page" (i.e., the resource status or summary page), or on a detail page where the user had to click on something in order to access the page. The visibility descriptor was meant to help express this concept. It allows attributes, operations, and notifications to be ranked from 1 to 4. The value 1 is supposed to indicate the coarsest-grained, most often visible elements, and 4 is supposed to indicate the finest-grained, more advanced, least often visible elements. An enterprise manager may ask only for model MBeans with a visibility value of 1 . Or if displaying a resource summary page, the enterprise manager would display only attributes with a visibility value of 1 . If the resource w ere clicked on, another page would be displayed that contained all of the attributes and operations regardless of visibility. Of course, assigning visibility values is very subjective and should be done by someone who understands the resource and the management systems managing that resource.

4.6.6.3 Export

The export field is valid only in theMBean-level descriptor. It signifies to the MBeanServer and model MBean constructor that this model MBean should be advertised so that other MBeanServers or remote management systems can find it. This field was intended to allow a management system to locate an MBean without necessarily knowing which MBeanServer houses it beforehand. One common place that an MBean may be exported to is a directory accessible via JNDI. If the export field's value is set to null , then the MBean is not exported. If it is not null , then its value is used by the export support in the MBeanServer of the model MBean itself to perform the export. So, for example, if the MBean were to be registered via JNDI, the export descriptor's value would contain the JNDI directory URI (Uniform Resource Identifier) and the JNDI name to be used. If the MBean were to be simultaneously registered with several MBeanServers, the export value might be the MBeanServer's host name and domain name. Here is an example:

 "export=jndiserver:8080:SpeedBean" 

Not all MBeanServers support the export of model MBeans. In fact, the JMX reference implementation does not. If the MBeanServer and model MBean implementations do not support it, this field is simply ignored. The default value for export is null .

4.6.6.4 Protocol Map

JMX was intended to allow the translation of MBean data and data models into other management technologies and their data models. This translation cannot always be generated. Sometimes JMX management data must be mapped to a specific data model in a specific technology. For example, you might define a set of MBeans for your HTTP Web server. The IETF ^[14] has also defined a MIB for managing Web servers. ^[15]

If you know that you want your MBean attributes to be accessed by SNMP ^[16] managers through the HTTP MIB, ^[17] then you can define a protocol map in the attribute descriptor that will define the protocol and object to map to. You can define multiple mappings for your attribute in the protocol map. The same attribute can be mapped to an SNMP MIB and a CIM ^[18] object property.

The protocolMap descriptor contains a reference to a protocolMap object. The protocolMap object is actually a descriptor with name/value pairs. The name is the protocol name, and the value is the mapped object name for the protocol for this attribute.

So for an MBean attribute status with SNMP and CIM maps, you would have the following name/value pairs:

 "SNMP=1.3.6.1.1.1.3.1.1.5.1" // maps to this SNMP OID  "CIM=cim_service.status"     // maps to the status attribute of                              // the cim_service abstract class 

Adapters will be the ones accessing and using the protocol map to translate the attributes into their own data model correctly. The adapters will have to recognize the protocol names as hints for their translation.

Attributes do not have to have specific protocol maps for all potential protocols that might make the attributes available through adapters. The adapter could generate a generic mapping for all attributes in all MBeans. The mapping would be realized and enforced by the adapter, not by the definition of a protocol map. For example, a MIB generator could be executed when new JMX MBeans were registered. This MIB generator would create a new SNMP MIB that would be loaded by the SNMP management system and used by the SNMP adapter. This is convenient because all the MBean's protocol map descriptors do not have to be updated whenever a new adapter to a new management protocol is registered with the MBeanServer.