Design for a Snapshot trigger API

This page will be used to record the design considerations etc for the Snapshot API . Eventually this information will end up in the formal documentation.

When triggering a dump from within a  JVM various considerations need reviewed.

Usecases

There are three usecases:

1. The caller is a monitoring application and requires a fast method of capturing and reporting a defined set of data.
2. The caller is post mortem analysis program which wants a specific set of data for specific types of problem analysis
3. The caller is an existing consumer of a dump format and just wants to use the API to trigger the dump.

Other considerations

Existing dumps cannot be subsetted and so we need to record what is available and provide a design where that information can be used in a reasonable manner.

If we need the caller to have set specific properties, command line options etc before we can produce a dump we need to find a way to communicate this.

Since we know about existing dumps it seem sensible for the RI to codify discovery and triggering of these dumps. 

The first level of optionality is by data type. We need to determine other levels of optionality or scope

Design

The main entry point for triggering a dump will be the DumpFactory class.    This class uses a singleton design pattern to create a default factory populated with auto discovered trigger classes.

The DumpFactory allows for a default trigger to be registered. By default it will be the first trigger class discovered.  To allow easy use of the RI code a System property will be used to allow

overriding  the  the first trigger class to be loaded.  

The contents of a Dump can be manipulated by creating an instance of a DumpDescriptor and setting the requirements accordingly.  Note that the general principle of a descriptor is to describe the least information required.  It is not desireable to have a design where data is required to not be present.

Users of the dump factory can generate a dump quickly by using the DumpFactory.getDefault().dump()  method chain.

For more sophisticated usage there are various options

1. For a snapshot dump triggered dynamically the user can create a DumpDescriptor desc and pass it into the DumpFactory to as follows :   DumpFactory.getDefault().dump(desc) 
2. For a repeatable dump snapshot method the user can take the DumpDescriptor and create a DumpHandle. The DumpHandle can be used to trigger a dump repeatedly:  DumpFactory.getDefault().getDumpHandle(desc).dump();

Example code

DumpFactory.getDefault().dump();

DumpFactory.getDefault().dump("hprof.signal.triggered");

DumpDescriptor desc=new DumpDescriptor();
desc.setIncludeJavaClasses(true);
desc.setIncludeJavaClassLoaders(true);
DumpFactory.getDefault().dump(desc);

DumpDescriptor desc=new DumpDescriptor();
desc.setIncludeJavaClasses(true);
desc.setIncludeJavaClassLoaders(true);

DumpHandle handle=DumpFactory.getDefault().createDumpHandle(desc);

handle.dump();

Available data

The matrix below outlines the data types that are available with Dumps from IBM and Sun JVMs

Full Size | Edit Diagram | Remove Diagram