8054834: Modular Source Code
Reviewed-by: alanb, chegar, ihse, mduigou
Contributed-by: alan.bateman@oracle.com, alex.buckley@oracle.com, chris.hegarty@oracle.com, erik.joelsson@oracle.com, jonathan.gibbons@oracle.com, karen.kinnear@oracle.com, magnus.ihse.bursie@oracle.com, mandy.chung@oracle.com, mark.reinhold@oracle.com, paul.sandoz@oracle.com
#==============================================================================
# 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.
#==============================================================================
#==============================================================================