JVM TI Demonstration Code

The Java™ Virtual Machine Tools Interface (JVM TI) is a native tool interface provided in JDK 5.0 and newer. Native libraries that use JVM TI and are loaded into the Java Virtual Machine via the -agentlib, -agentpath, or -Xrun (deprecated) interfaces, are called Agents.

JVM TI was designed to work with the Java Native Interface (JNI), and eventually displace the Java Virtual Machine Debugging Interface (JVMDI) and the Java Virtual Machine Profiling Interface (JVMPI).

We have created a set of demonstration agents that should help show many of the features and abilities of the interface. This list of demonstration agents will change over time. They are provided as educational tools and as starting points for Java tool development.

These agents are built with every JDK build and some basic testing is performed on a regular basis, but no extensive testbases currently exist for these agents. Every JDK installation should include all the pre-built binaries and sources for all these agents, just look in the demo/jvmti directory of your JDK.

Using or Running These Agents

Using these agents will require the VM to locate the shared library file before any actual Java code is run. The JDK installation should contain all the agent libraries in the ${JAVA_HOME}/demo/jvmti/agent-name/lib directories. The Solaris 64bit version would be contained in the sparcv9 or amd64 subdirectory. If 'java' complains that it can't find the library, you may need to add the directory containing the library into the LD_LIBRARY_PATH environment variable (Unix), or the PATH environment variable (Windows). This is system and platform specific. If you are using 64bit Solaris (e.g. 'java -d64'), you should use LD_LIBRARY_PATH64. Some agents such as the jdwp (debugger backend) are located inside the primary JDK directories and will always be found in those locations.

The agents that instrument classfiles (i.e. BCI, usually through the java_crw_demo library) such as heapTracker, mtrace, and minst, also need to have the Java classes they use available in the bootclasspath. The agents will make attempts at automatically adding their jar file (e.g. heapTracker.jar, mtrace.jar, or minst.jar) to the bootclasspath with AddToBootstrapClassLoaderSearch from JVM TI at startup (see the agent_util code). This is done by locating this jar file at ${JAVA_HOME}/demo/jvmti/agent-name where JAVA_HOME is obtained by calling GetSystemProperty from JVM TI with "java.home". We recognize that this is not ideal, but felt that as just demonstration code it was acceptable. Ideally the agent could find out the actual directory it came from and locate the jar file relative to that location. Our demonstration agents currently do not do this.

If you choose to modify or change these agents, the above information is important in making everything is found. It is recommended that you change the name of the agent when you modify it to avoid conflicts with the existing demo agents. Or better yet, go to http://jdk.dev.java.net and submit your changes to the agent as an RFE to the JDK.

Demonstration Agents Available

Agent Support

Native Library Build Hints

All libraries loaded into java are assumed to be MT-safe (Multi-thread safe). This means that multiple threads could be executing the code at the same time, and static or global data may need to be placed in critical sections. See the Raw Monitor interfaces for more information.

All native libraries loaded into the Java Virtual Machine, including Agent libraries, need to be compiled and built in a compatible way. Certain native compilation options or optimizations should be avoided, and some are required. More information on this options is available in the man pages for the various compilers.

Some native compiler and linker options can create fatal or erroneous behavior when native agent libraries are operating inside the Java Virtual Machine. It would take too many words to describe all the possible issues with all the native compiler options, optimizations, and settings. Here are some recommendations on the basic compiler and linker options we recommend:

For More Information

Remember, the complete source to all these agents is contained in the JDK installations at demo/jvmti.

For more detailed information on JVM TI, refer to http://java.sun.com/j2se/latest/docs/guide/jvmti.

More information on using JNI and building native libraries refer to: http://java.sun.com/j2se/latest/docs/guide/jni.

Additional information can also be found by doing a search on "jvmti" at http://java.sun.com/j2se. Various technical articles are also available through this website. And don't forget the Java Tutorials at http://docs.oracle.com/javase/tutorial for getting a quick start on all the various interfaces.

Comments and Feedback

Comments regarding JVM TI or on any of these demonstrations should be sent through http://java.sun.com/mail/