VDBMetadataCache JMX MBean Documentation

Overview

The VDBMetadataCache now includes JMX MBean support for monitoring and controlling the metadata cache when running under an application server.

MBean ObjectName

com.heirloomcomputing.ecs.isamsql:type=VDBMetadataCache

Available MBean Operations

Monitoring Operations

• getCacheStatistics() - Returns comprehensive cache statistics including:
  • Cache enabled status
  • TTL settings for all cache types
  • Hit/miss ratios for table, column, and connection caches
  • Current cache sizes
  • Overall hit rate percentage
  • Total evictions

Cache Data Inspection Operations

• getCachedTableNames() - Returns array of all table names currently in cache
• getTableMetadata(String tableName) - Returns detailed metadata for a specific cached table including:
  • Table existence status
  • Actual table name (case-sensitive)
  • Whether it's a view
  • Catalog and schema information
  • Cache age and expiration status
• getColumnMetadata(String tableName) - Returns column information for a specific cached table including:
  • Number of columns
  • Column names, types, and lengths
  • Cache age and expiration status
• getTableCacheContents() - Returns formatted summary of all entries in table cache
• getColumnCacheContents() - Returns formatted summary of all entries in column cache
• getConnectionCacheContents() - Returns formatted summary of all entries in connection cache including database info
• getTableCacheSize() - Returns number of entries in table cache
• getColumnCacheSize() - Returns number of entries in column cache
• getConnectionCacheSize() - Returns number of entries in connection cache

Management Operations

• clearAllCaches() - Clear all cache entries (table, column, and connection caches)
• clearTableCache(String tableName) - Clear cache entries for a specific table
• resetStatistics() - Reset all cache statistics to zero

Configuration Operations

• isEnabled() / setEnabled(boolean) - Enable or disable the cache
• getCacheTTL() / setCacheTTL(long) - Get/set cache time-to-live in milliseconds
• getMaxCacheEntries() / setMaxCacheEntries(int) - Get/set maximum number of cache entries

Using Cache Inspection Features

The enhanced MBean now provides detailed visibility into cached metadata. This is particularly useful for:

1. Debugging database connectivity issues - Check what metadata is cached and whether it's expired
2. Performance tuning - See which tables are cached and their hit rates
3. Troubleshooting - Verify that expected tables are in cache and inspect their metadata
4. Cache management - Identify stale entries and selectively clear specific tables

Example JConsole Usage

1. Connect to your application with JConsole
2. Navigate to MBeans → com.heirloomcomputing.ecs.isamsql → VDBMetadataCache
3. In the Attributes section, you can view:
   • CachedTableNames - Array of all cached table names
   • TableCacheSize, ColumnCacheSize, ConnectionCacheSize - Current cache sizes
   • TableCacheContents - Formatted view of all cached tables
4. In the Operations section, you can invoke:
   • getTableMetadata("TABLE_NAME") - Get detailed info for a specific table
   • getColumnMetadata("TABLE_NAME") - Get column details for a specific table

Connecting with JConsole

1. Start your application server with the COBOL runtime

2. Launch JConsole:

   jconsole
   

3. Connect to your application server process
4. Navigate to the MBeans tab
5. Find the MBean under: com.heirloomcomputing.ecs.isamsql → VDBMetadataCache

Enabling JMX Remote Access

To access the MBean remotely, add these JVM options when starting your application server:

-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9999
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false

Note: For production environments, always enable authentication and SSL.

Cache Configuration via Properties

The cache can be configured through deploy.properties or system properties:

• vdb.metadata.cache.enabled - Enable/disable cache (default: false)
• vdb.metadata.cache.ttl - Cache TTL in milliseconds (default: 86400000 = 24 hours)
• vdb.metadata.cache.connection.ttl - Connection metadata TTL (default: 604800000 = 7 days)
• vdb.metadata.cache.max.entries - Maximum cache entries (default: 10000)

Implementation Details

The MBean is automatically registered when the VDBMetadataCache class is loaded. The registration happens in a static initialization block, ensuring the MBean is available as soon as the cache is used.

Key Features:

• Automatic registration on class loading
• Graceful handling of registration failures
• Support for re-registration if needed
• Unregister method for cleanup in application servers

Testing the MBean

A test program is available at test/TestVDBMetadataCacheMBean.java to verify MBean registration:

javac -cp build/classes/java/main test/TestVDBMetadataCacheMBean.java
java -cp build/classes/java/main:test TestVDBMetadataCacheMBean

This will start a test process that registers the MBean and displays its PID for JConsole connection.