IBM User Guide for Java V7 on Windows > Developing Java applications



Support for the Java Attach API

Your application can connect to another "target" virtual machine using the Java™ Attach API. Your application can then load an agent application into the target virtual machine, for example to perform tasks such as monitoring status.

Code for agent applications, such as JMX agents or JVMTI agents, is normally loaded during virtual machine startup by specifying special startup parameters. Requiring startup parameters might not be convenient for using agents on applications that are already running, such as WebSphere Application Servers. You can use the Java Attach API to load an agent at any time, by specifying the process ID of the target virtual machine. The Attach API capability is sometimes called the "late attach" capability.

Support for the Attach API is enabled by default.


Security considerations

The Java Attach API creates files and directories in a common directory. On Windows, security of the common directory and its subdirectories and files is handled by Windows security mechanisms. This means that only the process owner can connect to their processes.

You must secure access to the Java Attach API capability to ensure that only authorized users or processes can connect to another virtual machine. If you do not intend to use the Java Attach API capability, disable this feature using a Java system property. Set the com.ibm.tools.attach.enable system property to the value no; for example: 

-Dcom.ibm.tools.attach.enable=no
The Attach API can be enabled by setting the com.ibm.tools.attach.enable system property to the value yes; for example: 
-Dcom.ibm.tools.attach.enable=yes


Using the Java Attach API

By default, the target virtual machine is identified by its process ID. To use a different target, change the system property com.ibm.tools.attach.id; for example: 

-Dcom.ibm.tools.attach.id=<process_ID>

The target process also has a human-readable "display name". By default, the display name is the command line used to start Java. To change the default display name, use the com.ibm.tools.attach.displayName system property. The ID and display name cannot be changed after the application has started.

The Attach API creates working files in a common directory, which by default is called .com_ibm_tools_attach and is created in the system temporary directory. The system property java.io.tmpdir holds the value of the system temporary directory. On Windows systems, the system temporary directory is typically C:\Documents and Settings\<userid>\Local Settings\Temp.

You can specify a different common directory from the default, by using the following Java system property: 

-Dcom.ibm.tools.attach.directory=directory_name
This system property causes the specified directory, directory_name, to be used as the common directory. If the directory does not already exist, it is created, however the parent directory must already exist. For example, the following system property creates a common directory called myattachapidir in the C: directory. The C: directory must already exist. 
-Dcom.ibm.tools.attach.directory=C:\myattachapidir
The common directory must be located on a local drive; specifying a network mounted file system might result in incorrect behavior.

If your Java application ends abnormally, for example, following a crash or a SIGKILL signal, the process subdirectory is not deleted. The Java VM detects and removes obsolete subdirectories where possible. The subdirectory can also be deleted by the owning user ID.

On heavily loaded system, applications might experience timeouts when attempting to connect to target applications. The default timeout is 120 seconds. Use the com.ibm.tools.attach.timeout system property to specify a different timeout value in milliseconds. For example, to timeout after 60 seconds: 

-Dcom.ibm.tools.attach.timeout=60000
A timeout value of zero indicates an indefinite wait.

For JMX applications, you can disable authentication by editing the <JAVA_HOME>/jre/lib/management/management.properties file. Set the following properties to disable authentication in JMX: 

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

Problems with the Attach API result in one of the following exceptions:

A useful reference for information about the Attach API can be found at http://download.oracle.com/javase/7/docs/technotes/guides/attach/index.html. The IBM implementation of the Attach API is equivalent to the Oracle Corporation implementation. However, the IBM implementation cannot be used to attach to, or accept attach requests from, non-IBM virtual machines. To use the attach API to attach to target processes from your application, you must add the "tools.jar" library to the application classpath. This library is not required for the target processes to accept attach requests.


Parent: Developing Java applications








Error 404 - Not Found

Error 404 - Not Found

The document you are looking for may have been removed or re-named. Please contact the web site owner for further assistance.