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

#          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.

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

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