#==============================================================================

# JVM Management MIB - Instrumentation Classes

#==============================================================================

In this directory:

------------------

README: this file

commands.env: a file containing some ksh variables & functions

that I have used to generate & compile all the

stuff. Probably only valid in my own environment.

logging.properties: logging.properties file that can be used to obtain

trace information.

*.java: utility and custom classes for the JVM Management MIB.

These classes show how to provide instrumentation for

a mibgen generated MIB, how to simulate virtual tables,

and how to make use of the SnmpUserDataFactory.

Only the jvmMemory group and its tables are instrumented.

Dependency

----------

jvmManagementMib.txt : the JVM Management MIB module in compilable form.

Tiger SNMP Runtime : SNMP Runtime classes for Tiger. We assume these

classes could be part of the JMX delivery

(classes in com.sun.jmx.snmp.*)

JDMK 5.1 : The jdmktk.jar contains the com.sun.jdmk.tools.MibGen class

used to compile the MIB. JDMK also has a mibgen.sh script

to start mibgen. By default mibgen generates code that can

integrate with JDMK SNMP runtime. In order to generate

code that integrate with Tiger SNMP runtime, you need to

start mibgen with a non-default resource file.

JDMK 5.1 workspace contains a mibgen resource file

specific for tiger: mibgen.property.tiger

Custom Instrumentation Code: the files in this directory.

How to proceed:

---------------

Get mibgen from JDMK 5.1. Start mibgen with mibgen resource file for

tiger (add -Dcom.sun.jdmk.tools.mibgen.config.file=<mibgen.properties.tiger>)

on the Java command line.

Use mibgen to generate code for the jvmManagementMib.txt file. Note that

the custom classes provided in this directory are all in the

sun.management.snmp.jvminstr package, and expect the generated classes to

be in another sun.management.snmp.jvmmib package (use mibgen option

-tp sun.management.snmp.jvmmib)

If this package name does not suit you, simply change it to something else,

both in the custom classes below (you might use 'sed' or do it manually)

and in the -tp option that you will pass to mibgen.

It is recommended to generate all classes in a different directory (if

you read command.env you will see that I have put the custom classes

in a "custom" directory, and the generated classes in a "parsed"

directory. This makes it easier to cleanup the mib. You can safely

do a rm -rf <parsed> and call mibgen again.

Then compile the generated classes - you will need JMX and Tiger SNMP

runtime classes in your classpath - if you compile with a tiger build that

already have them then you don't need to specify anything special.

Then make your classpath point to the compiled generated classes, and

compile the custom code in this directory.

Then you can use the SnmpDaemonTest class to start a JVM with the

intsrumented MIB, and you can use e.g. the easymanager contrib of

JDMK to view the MIB through SNMP.

#==============================================================================

# Classes Details

#==============================================================================

Utility Classes developped for the JVM Management MIB:

------------------------------------------------------

JvmContextFactory.java : The context factory allocates a Map that

serves as request contextual cache.

Values obtained from JSR 163 API can be

cached in this object.

A request contextual cache is allocated

each time a request is being processed,

and is released at the end of processing.

Object: 1) preserve atomicity

2) minimize API calls

3) ensure consistency of the

various pieces of data returned.

MibLogger.java : Send traces to java.util.logging

SnmpTableHandler.java : an interface used to access table data.

SnmpCachedData.java : This object can be use to cache a snapshot

of the data contained in a table.

SnmpTableCache.java : A weak cache for table data. The data is

computed on demand and cached in a

weakreference. Makes it possible to specify

a validity period for the cache data.

SnmpListTableCache.java : Extends SnmpTableCache - for tables whose

data is returned in a List object.

SnmpNamedListTableCache.java : Extends SnmpListTableCache - for tables whose

elements can be named by a unique string.

SnmpDaemonTest.java : A dummy standalone SNMP agent that registers

the JVM Managemnt MIB in Tiger's SNMP

adaptor. This is the "main". Note that

this not the class that will be used to

start the adaptor in the final Tiger - it is

just a dummy test main.

JVM Management MIB

------------------

JVM_MANAGEMENT_MIB_IMPL.java : subclasses the generated JVM_MANAGEMENT_MIB

class.

Object: overriding factory method in order

to instantiate custom code instead

of generated code.

JVM Memory Group

----------------

JvmMemoryImpl.java : Provides instrumentation for the jvmMemory

group. Replaces the generated JvmMemory class,

which is not used and can be thrown away.

Implements the generated JvmMemoryMBean

interface (which was also implemented by

the generated JvmMemory skeleton class)

Use the request contextual cache

in order to ensure consistency when

returning MemoryUsage datas. Note that all

tables in this group have been implemented

as virtual tables. As a consequence, the

generated TableJvmMemXXXXXTable.java classes

are not needed.

JvmMemoryMetaImpl.java : Custom MetaData class for the jvmMemory group.

Subclasses the generated JvmMemoryMeta class.

Object: overrides the factory methods in order

to instantiate custom meta data classes

for the jvmMemManagerTable,

jvmMemGCTable,

jvmMemPoolTable,

jvmMemMgrPoolRelTable.

JVM Memory Manager Table

------------------------

JvmMemManagerTableMetaImpl.java : Custom MetaData class for the

jvmMemManagerTable. This MetaData traps

all the SNMP Runtime calls made to the

table - in order to make the Memory Manager

table virtual: i.e. the table does not have

to be maintained permanently in memory.

Instead, the table is computed "on demand",

and the data is cached in a weak cache

(see SnmpNamedListTableCache) which remains

valid for a few ms. If the data is found

to be obsolete, or was garbage collected,

the table is recomputed.

JvmMemManagerEntryImpl.java : Custom Entry class for jvmMemManagerTable.

Entries are created on the fly when it

becomes necessary to get data from a

Memory Managers. They are temporary objects

that wrap the MemoryManager just for the

call duration - and are released just after.

JVM Memory GC Table

-------------------

JvmMemGCTableMetaImpl.java : Custom MetaData class for the

jvmMemGCTable. This MetaData traps

all the SNMP Runtime calls made to the

table - in order to make the GC

table virtual: the GC table reuses the

cached data computed for the

jvmMemManagerTable - simply acting as a

filter that only shows those elements that

are instance of GarbageCollectorMetrics.

In other words it implements a fitered view

of the jvmMemManagerTable.

JvmMemGCEntryImpl.java : Provide access to the data specific to

GarbageCollectorMetrics objects. Objects

of this classes are created on the fly,

when data needs to be returned from a

GarbageCollectorMetrics object, and are

released just after. They are not kept in

memory.

JVM Memory Pool Table

---------------------

JvmMemPoolTableMetaImpl.java : Custom MetaData class for the jvmMemPoolTable.

This is quite similar to what was done for

the jvmMemManagerTable in

JvmMemManagerTableMetaImpl. Most of the code

here was obtain by cut&paste-ing from

JvmMemManagerTableMetaImpl and replacing

"Manager" with "Pool".

JvmMemPoolEntryImpl.java : Provide access to the data specific to

MemoryPoolMetrics objects. Objects

of this classes are created on the fly,

when data needs to be returned from a

MemoryPoolMetrics object, and are

released just after. They are not kept in

memory. Use the request contextual cache

in order to ensure consistency when

returning MemoryUsage datas.

JVM Memory Manager / Memory Pool Relation Table

------------------------------------------------

JvmMemMgrPoolRelTableMetaImpl.java : Custom MetaData class for the

jvmMemMgrPoolRelTable. This meta data

uses the JvmMemManagerTableMetaImpl and

JvmMemPoolTableMetaImpl in order to

find out the content of the

jvmMemManagerTable and the mapping between

Memory Pool Name and Memory Pool Index.

For each element of the jvmMemManagerTable

it calls the JSR 163 APIs to find the

related Memory Pool, then finds out their

index, and then creates the corresponding

row in the jvmMemMgrPoolRelTable cached data.

Like all the other tables, this table is

virtual: the data is kept on a weak cache

and recomputed on demand, if its validity

as expired or if it has been gc'ed.

JvmMemMgrPoolRelEntryImpl.java : A simple couple MemoryManager/MemoryPool.

Models a row in the jvmMemMgrPoolRelTable.

Objects of this type are cached in the

jvmMemMgrPoolRelTable cached data.

#==============================================================================

#==============================================================================