lang

Package Specification

An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the agent class which will be loaded to start the agent. For implementations that support a command-line interface, an agent is started by specifying an option on the command-line. Implementations may also support a mechanism to start agents some time after the VM has started. For example, an implementation may provide a mechanism that allows a tool to attach to a running application, and initiate the loading of the tool's agent into the running application. The details as to how the load is initiated, is implementation dependent.

Command-Line Interface

On implementations with a command-line interface, an agent is started by adding this option to the command-line:

-javaagent:jarpath[=options]

The manifest of the agent JAR file must contain the attribute Premain-Class. The value of this attribute is the name of the agent class. The agent class must implement a public static premain method similar in principle to the main application entry point. After the Java Virtual Machine (JVM) has initialized, each premain method will be called in the order the agents were specified, then the real application main method will be called. Each premain method must return in order for the startup sequence to proceed.

The premain method has one of two possible signatures. The JVM first attempts to invoke the following method on the agent class:

public static void premain(String agentArgs, Instrumentation inst);

If the agent class does not implement this method then the JVM will attempt to invoke:

public static void premain(String agentArgs);

The agent class may also have an agentmain method for use when the agent is started after VM startup. When the agent is started using a command-line option, the agentmain method is not invoked.

The agent class will be loaded by the system class loader (see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is the class loader which typically loads the class containing the application main method. The premain methods will be run under the same security and classloader rules as the application main method. There are no modeling restrictions on what the agent premain method may do. Anything application main can do, including creating threads, is legal from premain.

Each agent is passed its agent options via the agentArgs parameter. The agent options are passed as a single string, any additional parsing should be performed by the agent itself.

If the agent cannot be resolved (for example, because the agent class cannot be loaded, or because the agent class does not have an appropriate premain method), the JVM will abort. If a premain method throws an uncaught exception, the JVM will abort.

Starting Agents After VM Startup

An implementation may provide a mechanism to start agents sometime after the the VM has started. The details as to how this is initiated are implementation specific but typically the application has already started and its main method has already been invoked. In cases where an implementation supports the starting of agents after the VM has started the following applies:

1. The manifest of the agent JAR must contain the attribute Agent-Class. The value of this attribute is the name of the agent class.

2. The agent class must implement a public static agentmain method.

3. The system class loader ( {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must support a mechanism to add an agent JAR file to the system class path.

The agent JAR is appended to the system class path. This is the class loader that typically loads the class containing the application main method. The agent class is loaded and the JVM attempts to invoke the agentmain method. The JVM first attempts to invoke the following method on the agent class:

public static void agentmain(String agentArgs, Instrumentation inst);

If the agent class does not implement this method then the JVM will attempt to invoke:

public static void agentmain(String agentArgs);

The agent class may also have an premain method for use when the agent is started using a command-line option. When the agent is started after VM startup the premain method is not invoked.

The agent is passed its agent options via the agentArgs parameter. The agent options are passed as a single string, any additional parsing should be performed by the agent itself.

The agentmain method should do any necessary initialization required to start the agent. When startup is complete the method should return. If the agent cannot be started (for example, because the agent class cannot be loaded, or because the agent class does not have a conformant agentmain method), the JVM will not abort. If the agentmain method throws an uncaught exception it will be ignored.

Manifest Attributes

Premain-Class

When an agent is specified at JVM launch time this attribute specifies the agent class. That is, the class containing the premain method. When an agent is specified at JVM launch time this attribute is required. If the attribute is not present the JVM will abort. Note: this is a class name, not a file name or path.

Agent-Class

If an implementation supports a mechanism to start agents sometime after the VM has started then this attribute specifies the agent class. That is, the class containing the agentmain method. This attribute is required, if it is not present the agent will not be started. Note: this is a class name, not a file name or path.

Boot-Class-Path

A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as JAR or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed. Paths in the list are separated by one or more spaces. A path takes the syntax of the path component of a hierarchical URI. The path is absolute if it begins with a slash character ('/'), otherwise it is relative. A relative path is resolved against the absolute path of the agent JAR file. Malformed and non-existent paths are ignored. When an agent is started sometime after the VM has started then paths that do not represent a JAR file are ignored. This attribute is optional.

Can-Redefine-Classes

Boolean (true or false, case irrelevant). Is the ability to redefine classes needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

Can-Retransform-Classes

Boolean (true or false, case irrelevant). Is the ability to retransform classes needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

Can-Set-Native-Method-Prefix

Boolean (true or false, case irrelevant). Is the ability to set native method prefix needed by this agent. Values other than true are considered false. This attribute is optional, the default is false.

An agent JAR file may have both the Premain-Class and Agent-Class attributes present in the manifest. When the agent is started on the command-line using the -javaagent option then the Premain-Class attribute specifies the name of the agent class and the Agent-Class attribute is ignored. Similarly, if the agent is started sometime after the VM has started, then the Agent-Class attribute specifies the name of the agent class (the value of Premain-Class attribute is ignored).

Related Documentation

• JDK Tools and Utilities

Platform MXBeans

Management Interface	Description
{@link java.lang.management.ClassLoadingMXBean}	Class loading system of the Java virtual machine.
{@link java.lang.management.CompilationMXBean}	Compilation system of the Java virtual machine.
{@link java.lang.management.MemoryMXBean}	Memory system of the Java virtual machine.
{@link java.lang.management.ThreadMXBean}	Threads system of the Java virtual machine.
{@link java.lang.management.RuntimeMXBean}	Runtime system of the Java virtual machine.
{@link java.lang.management.OperatingSystemMXBean}	Operating system on which the Java virtual machine is running.
{@link java.lang.management.GarbageCollectorMXBean}	Garbage collector in the Java virtual machine.
{@link java.lang.management.MemoryManagerMXBean}	Memory manager in the Java virtual machine.
{@link java.lang.management.MemoryPoolMXBean}	Memory pool in the Java virtual machine.

A platform MXBean is a managed bean that defines the management interface for one component for the platform and is specified in the ManagementFactory class.

An application can monitor the instrumentation of the Java virtual machine and manage certain characteristics in the following ways:

• Direct access to an MXBean interface
  1. Get the MXBean instance through the static factory method and access the MXBean interface locally of the running virtual machine.
  2. Construct an MXBean proxy instance that forwards the method calls to a given {@link javax.management.MBeanServer MBeanServer} by calling {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy ManagementFactory.newPlatformMXBeanProxy}. A proxy is typically constructed to remotely access an MXBean of another running virtual machine.
• Indirect access via {@link javax.management.MBeanServer MBeanServer} interface
  1. Go through the {@link java.lang.management.ManagementFactory#getPlatformMBeanServer platform MBeanServer} to access MXBeans locally or a specific MBeanServerConnection to access MXBeans remotely. The attributes and operations of an MXBean use only JMX open types which include basic data types, {@link javax.management.openmbean.CompositeData CompositeData}, and {@link javax.management.openmbean.TabularData TabularData} defined in {@link javax.management.openmbean.OpenType OpenType}.

ManagementFactory

A platform MBeanServer can be accessed with the {@link java.lang.management.ManagementFactory#getPlatformMBeanServer getPlatformMBeanServer} method. On the first call to this method, it creates the platform MBeanServer and registers all platform MXBeans including platform MXBeans defined in other packages such as {@link java.util.logging.LoggingMXBean}. Each platform MXBean is registered with a unique name defined in the {@link java.lang.management.ManagementFactory ManagementFactory} class for constructing {@link javax.management.ObjectName ObjectName}. This is a single MBeanServer that can be shared by different managed components running within the same Java virtual machine.

Interoperability

A data type used by the MXBean interfaces are mapped to an open type when being accessed via MBeanServer interface. The data type mapping is specified in the {@link java.lang.management.ManagementFactory ManagementFactory} class.

Ways to Access MXBeans

1. Call the methods in the MXBean directly within the same Java virtual machine.

      RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
   
      // Get the standard attribute "VmVendor"
      String vendor = mxbean.getVmVendor();
   
   

2. Go through a MBeanServerConnection connecting to the platform MBeanServer of a running virtual machine.

   MBeanServerConnection mbs;

   // Connect to a running JVM (or itself) and get MBeanServerConnection
   // that has the JVM MXBeans registered in it
   ...

   try {
       // Assuming the RuntimeMXBean has been registered in mbs
       ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
    
       // Get standard attribute "VmVendor"
       String vendor = (String) mbs.getAttribute(oname, "VmVendor");
   } catch (....) {
       // Catch the exceptions thrown by ObjectName constructor
       // and MBeanServer.getAttribute method
       ...
   }

3. Use MXBean proxy.

   MBeanServerConnection mbs;

   // Connect to a running JVM (or itself) and get MBeanServerConnection
   // that has the JVM MBeans registered in it
   ...

   // Get a MBean proxy for RuntimeMXBean interface
   RuntimeMXBean proxy = 
       ManagementFactory.newPlatformMXBeanProxy(mbs,
                                                ManagementFactory.RUNTIME_MXBEAN_NAME,
                                                RuntimeMXBean.class);
   // Get standard attribute "VmVendor" 
   String vendor = proxy.getVmVendor();

Platform Extension

It is recommended to name the platform-specific attributes with a vendor-specific prefix such as the vendor's name to avoid collisions of the attribute name between the future extension to the standard management interface and the platform extension. If the future extension to the standard management interface defines a new attribute for a management interface and the attribute name is happened to be same as some vendor-specific attribute's name, the applications accessing that vendor-specific attribute would have to be modified to cope with versioning and compatibility issues.

Below is an example showing how to access a platform-specific attribute from Sun's implementation of the RuntimeMXBean.

1) Direct access to the Sun-specific MXBean interface

   com.sun.management.RuntimeMXBean mxbean = 
       (com.sun.management.RuntimeMXBean) ManagementFactory.getRuntimeMXBean();

   // Get the standard attribute "VmVendor"
   String vendor = mxbean.getVmVendor();

   // Get the platform-specific attribute "Bar"
   BarType bar = mxbean.getBar();

2) Access the Sun-specific MXBean interface via MBeanServer

   MBeanServerConnection mbs;

   // Connect to a running JVM (or itself) and get MBeanServerConnection
   // that has the JVM MXBeans registered in it
   ...

   try {
       // Assuming the RuntimeMXBean has been registered in mbs
       ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
    
       // Get standard attribute "VmVendor"
       String vendor = (String) mbs.getAttribute(oname, "VmVendor");

       // Check if this MXBean contains Sun's extension
       if (mbs.isInstanceOf(oname, "com.sun.management.RuntimeMXBean")) {
           // Get platform-specific attribute "Bar"
           BarType bar = (String) mbs.getAttribute(oname, "Bar");
       }
   } catch (....) {
       // Catch the exceptions thrown by ObjectName constructor
       // and MBeanServer methods
       ...
   }

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

The java.lang.management API is thread-safe. @see JMX Specification. @author Mandy Chung @version 1.17, 05/05/07 @since 1.5

Package Specification

Each reference-object type is implemented by a subclass of the abstract base {@link java.lang.ref.Reference} class. An instance of one of these subclasses encapsulates a single reference to a particular object, called the referent. Every reference object provides methods for getting and clearing the reference. Aside from the clearing operation reference objects are otherwise immutable, so no set operation is provided. A program may further subclass these subclasses, adding whatever fields and methods are required for its purposes, or it may use these subclasses without change.

Notification

The relationship between a registered reference object and its queue is one-sided. That is, a queue does not keep track of the references that are registered with it. If a registered reference becomes unreachable itself, then it will never be enqueued. It is the responsibility of the program using reference objects to ensure that the objects remain reachable for as long as the program is interested in their referents.

While some programs will choose to dedicate a thread to removing reference objects from one or more queues and processing them, this is by no means necessary. A tactic that often works well is to examine a reference queue in the course of performing some other fairly-frequent action. For example, a hashtable that uses weak references to implement weak keys could poll its reference queue each time the table is accessed. This is how the {@link java.util.WeakHashMap} class works. Because the {@link java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll} method simply checks an internal data structure, this check will add little overhead to the hashtable access methods.

Automatically-cleared references

Reachability

• An object is strongly reachable if it can be reached by some thread without traversing any reference objects. A newly-created object is strongly reachable by the thread that created it.
• An object is softly reachable if it is not strongly reachable but can be reached by traversing a soft reference.
• An object is weakly reachable if it is neither strongly nor softly reachable but can be reached by traversing a weak reference. When the weak references to a weakly-reachable object are cleared, the object becomes eligible for finalization.
• An object is phantom reachable if it is neither strongly, softly, nor weakly reachable, it has been finalized, and some phantom reference refers to it.
• Finally, an object is unreachable, and therefore eligible for reclamation, when it is not reachable in any of the above ways.

Unless otherwise specified in a particular implementation, the collections returned by methods in this package should be expected to be unmodifiable by the caller and unsafe for concurrent access.

Unless otherwise specified, methods in this package will throw a NullPointerException if given a null argument.
author:
   Joseph D.

Unless otherwise specified in a particular implementation, the collections returned by methods in this package should be expected to be unmodifiable by the caller and unsafe for concurrent access.

Unless otherwise specified, methods in this package will throw a NullPointerException if given a null argument.
author:
   Joseph D.