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

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