001: /*
002: * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.attach;
027:
028: import com.sun.tools.attach.spi.AttachProvider;
029: import java.util.ArrayList;
030: import java.util.List;
031: import java.util.Properties;
032: import java.io.IOException;
033:
034: /**
035: * A Java virtual machine.
036: *
037: * <p> A <code>VirtualMachine</code> represents a Java virtual machine to which this
038: * Java virtual machine has attached. The Java virtual machine to which it is
039: * attached is sometimes called the <i>target virtual machine</i>, or <i>target VM</i>.
040: * An application (typically a tool such as a managemet console or profiler) uses a
041: * VirtualMachine to load an agent into the target VM. For example, a profiler tool
042: * written in the Java Language might attach to a running application and load its
043: * profiler agent to profile the running application. </p>
044: *
045: * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method
046: * with an identifier that identifies the target virtual machine. The identifier is
047: * implementation-dependent but is typically the process identifier (or pid) in
048: * environments where each Java virtual machine runs in its own operating system process.
049: * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the
050: * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link
051: * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained
052: * from the list of virtual machine descriptors returned by the {@link #list list} method.
053: * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent},
054: * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath}
055: * methods are used to load agents into target virtual machine. The {@link
056: * #loadAgent loadAgent} method is used to load agents that are written in the Java
057: * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See
058: * {@link java.lang.instrument} for a detailed description on how these agents
059: * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
060: * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
061: * are deployed in a dynamic library and make use of the <a
062: * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
063: * Interface</a>. </p>
064: *
065: * <p> In addition to loading agents a VirtualMachine provides read access to the
066: * {@link java.lang.System#getProperties() system properties} in the target VM.
067: * This can be useful in some environments where properties such as
068: * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are
069: * used to construct the path to agent that will be loaded into the target VM.
070: *
071: * <p> The following example demonstrates how VirtualMachine may be used:</p>
072: *
073: * <pre>
074: *
075: * // attach to target VM
076: * VirtualMachine vm = VirtualMachine.attach("2177");
077: *
078: * // get system properties in target VM
079: * Properties props = vm.getSystemProperties();
080: *
081: * // construct path to management agent
082: * String home = props.getProperty("java.home");
083: * String agent = home + File.separator + "lib" + File.separator
084: * + "management-agent.jar";
085: *
086: * // load agent into target VM
087: * vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000");
088: *
089: * // detach
090: * vm.detach();
091: *
092: * </pre>
093: *
094: * <p> In this example we attach to a Java virtual machine that is identified by
095: * the process identifier <code>2177</code>. The system properties from the target
096: * VM are then used to construct the path to a <i>management agent</i> which is then
097: * loaded into the target VM. Once loaded the client detaches from the target VM. </p>
098: *
099: * <p> A VirtualMachine is safe for use by multiple concurrent threads. </p>
100: *
101: * @since 1.6
102: */
103:
104: public abstract class VirtualMachine {
105: private AttachProvider provider;
106: private String id;
107: private volatile int hash; // 0 => not computed
108:
109: /**
110: * Initializes a new instance of this class.
111: *
112: * @param provider
113: * The attach provider creating this class.
114: * @param id
115: * The abstract identifier that identifies the Java virtual machine.
116: *
117: * @throws NullPointerException
118: * If <code>provider</code> or <code>id</code> is <code>null</code>.
119: */
120: protected VirtualMachine(AttachProvider provider, String id) {
121: if (provider == null) {
122: throw new NullPointerException("provider cannot be null");
123: }
124: if (id == null) {
125: throw new NullPointerException("id cannot be null");
126: }
127: this .provider = provider;
128: this .id = id;
129: }
130:
131: /**
132: * Return a list of Java virtual machines.
133: *
134: * <p> This method returns a list of Java {@link
135: * com.sun.tools.attach.VirtualMachineDescriptor} elements.
136: * The list is an aggregation of the virtual machine
137: * descriptor lists obtained by invoking the {@link
138: * com.sun.tools.attach.spi.AttachProvider#listVirtualMachines
139: * listVirtualMachines} method of all installed
140: * {@link com.sun.tools.attach.spi.AttachProvider attach providers}.
141: * If there are no Java virtual machines known to any provider
142: * then an empty list is returned.
143: *
144: * @return The list of virtual machine descriptors.
145: */
146: public static List<VirtualMachineDescriptor> list() {
147: ArrayList<VirtualMachineDescriptor> l = new ArrayList<VirtualMachineDescriptor>();
148: List<AttachProvider> providers = AttachProvider.providers();
149: for (AttachProvider provider : providers) {
150: l.addAll(provider.listVirtualMachines());
151: }
152: return l;
153: }
154:
155: /**
156: * Attaches to a Java virtual machine.
157: *
158: * <p> This method obtains the list of attach providers by invoking the
159: * {@link com.sun.tools.attach.spi.AttachProvider#providers()
160: * AttachProvider.providers()} method. It then iterates overs the list
161: * and invokes each provider's {@link
162: * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(java.lang.String)
163: * attachVirtualMachine} method in turn. If a provider successfully
164: * attaches then the iteration terminates, and the VirtualMachine created
165: * by the provider that successfully attached is returned by this method.
166: * If the <code>attachVirtualMachine</code> method of all providers throws
167: * {@link com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
168: * then this method also throws <code>AttachNotSupportedException</code>.
169: * This means that <code>AttachNotSupportedException</code> is thrown when
170: * the identifier provided to this method is invalid, or the identifier
171: * corresponds to a Java virtual machine that does not exist, or none
172: * of the providers can attach to it. This exception is also thrown if
173: * {@link com.sun.tools.attach.spi.AttachProvider#providers()
174: * AttachProvider.providers()} returns an empty list. </p>
175: *
176: * @param id
177: * The abstract identifier that identifies the Java virtual machine.
178: *
179: * @return A VirtualMachine representing the target VM.
180: *
181: * @throws SecurityException
182: * If a security manager has been installed and it denies
183: * {@link com.sun.tools.attach.AttachPermission AttachPermission}
184: * <tt>("attachVirtualMachine")</tt>, or another permission
185: * required by the implementation.
186: *
187: * @throws AttachNotSupportedException
188: * If the <code>attachVirtualmachine</code> method of all installed
189: * providers throws <code>AttachNotSupportedException</code>, or
190: * there aren't any providers installed.
191: *
192: * @throws IOException
193: * If an I/O error occurs
194: *
195: * @throws NullPointerException
196: * If <code>id</code> is <code>null</code>.
197: */
198: public static VirtualMachine attach(String id)
199: throws AttachNotSupportedException, IOException {
200: if (id == null) {
201: throw new NullPointerException("id cannot be null");
202: }
203: List<AttachProvider> providers = AttachProvider.providers();
204: if (providers.size() == 0) {
205: throw new AttachNotSupportedException(
206: "no providers installed");
207: }
208: AttachNotSupportedException lastExc = null;
209: for (AttachProvider provider : providers) {
210: try {
211: return provider.attachVirtualMachine(id);
212: } catch (AttachNotSupportedException x) {
213: lastExc = x;
214: }
215: }
216: throw lastExc;
217: }
218:
219: /**
220: * Attaches to a Java virtual machine.
221: *
222: * <p> This method first invokes the {@link
223: * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
224: * of the given virtual machine descriptor to obtain the attach provider. It
225: * then invokes the attach provider's {@link
226: * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(VirtualMachineDescriptor)
227: * attachVirtualMachine} to attach to the target VM.
228: *
229: * @param vmd
230: * The virtual machine descriptor.
231: *
232: * @return A VirtualMachine representing the target VM.
233: *
234: * @throws SecurityException
235: * If a security manager has been installed and it denies
236: * {@link com.sun.tools.attach.AttachPermission AttachPermission}
237: * <tt>("attachVirtualMachine")</tt>, or another permission
238: * required by the implementation.
239: *
240: * @throws AttachNotSupportedException
241: * If the attach provider's <code>attachVirtualmachine</code>
242: * throws <code>AttachNotSupportedException</code>.
243: *
244: * @throws IOException
245: * If an I/O error occurs
246: *
247: * @throws NullPointerException
248: * If <code>vmd</code> is <code>null</code>.
249: */
250: public static VirtualMachine attach(VirtualMachineDescriptor vmd)
251: throws AttachNotSupportedException, IOException {
252: return vmd.provider().attachVirtualMachine(vmd);
253: }
254:
255: /**
256: * Detach from the virtual machine.
257: *
258: * <p> After detaching from the virtual machine, any further attempt to invoke
259: * operations on that virtual machine will cause an {@link java.io.IOException
260: * IOException} to be thrown. If an operation (such as {@link #loadAgent
261: * loadAgent} for example) is in progress when this method is invoked then
262: * the behaviour is implementation dependent. In other words, it is
263: * implementation specific if the operation completes or throws
264: * <tt>IOException</tt>.
265: *
266: * <p> If already detached from the virtual machine then invoking this
267: * method has no effect. </p>
268: *
269: * @throws IOException
270: * If an I/O error occurs
271: */
272: public abstract void detach() throws IOException;
273:
274: /**
275: * Returns the provider that created this virtual machine.
276: *
277: * @return The provider that created this virtual machine.
278: */
279: public final AttachProvider provider() {
280: return provider;
281: }
282:
283: /**
284: * Returns the identifier for this Java virtual machine.
285: *
286: * @return The identifier for this Java virtual machine.
287: */
288: public final String id() {
289: return id;
290: }
291:
292: /**
293: * Loads an agent library.
294: *
295: * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
296: * TI</a> client is called an <i>agent</i>. It is developed in a native language.
297: * A JVM TI agent is deployed in a platform specific manner but it is typically the
298: * platform equivalent of a dynamic library. This method causes the given agent
299: * library to be loaded into the target VM (if not already loaded).
300: * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
301: * as specified in the
302: * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
303: * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
304: * function is invoked even if the agent library was loaded prior to invoking
305: * this method.
306: *
307: * <p> The agent library provided is the name of the agent library. It is interpreted
308: * in the target virtual machine in an implementation-dependent manner. Typically an
309: * implementation will expand the library name into an operating system specific file
310: * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
311: * <tt>libfoo.so</tt>, and located using the search path specified by the
312: * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
313: *
314: * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
315: * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
316: * thrown. The return value from the <code>Agent_OnAttach</code> can then be
317: * obtained by invoking the {@link
318: * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
319: * method on the exception. </p>
320: *
321: * @param agentLibrary
322: * The name of the agent library.
323: *
324: * @param options
325: * The options to provide to the <code>Agent_OnAttach</code>
326: * function (can be <code>null</code>).
327: *
328: * @throws AgentLoadException
329: * If the agent library does not exist, or cannot be loaded for
330: * another reason.
331: *
332: * @throws AgentInitializationException
333: * If the <code>Agent_OnAttach</code> function returns an error
334: *
335: * @throws IOException
336: * If an I/O error occurs
337: *
338: * @throws NullPointerException
339: * If <code>agentLibrary</code> is <code>null</code>.
340: *
341: * @see com.sun.tools.attach.AgentInitializationException#returnValue()
342: */
343: public abstract void loadAgentLibrary(String agentLibrary,
344: String options) throws AgentLoadException,
345: AgentInitializationException, IOException;
346:
347: /**
348: * Loads an agent library.
349: *
350: * <p> This convenience method works as if by invoking:
351: *
352: * <blockquote><tt>
353: * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
354: * </tt></blockquote>
355: *
356: * @param agentLibrary
357: * The name of the agent library.
358: *
359: * @throws AgentLoadException
360: * If the agent library does not exist, or cannot be loaded for
361: * another reason.
362: *
363: * @throws AgentInitializationException
364: * If the <code>Agent_OnAttach</code> function returns an error
365: *
366: * @throws IOException
367: * If an I/O error occurs
368: *
369: * @throws NullPointerException
370: * If <code>agentLibrary</code> is <code>null</code>.
371: */
372: public void loadAgentLibrary(String agentLibrary)
373: throws AgentLoadException, AgentInitializationException,
374: IOException {
375: loadAgentLibrary(agentLibrary, null);
376: }
377:
378: /**
379: * Load a native agent library by full pathname.
380: *
381: * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
382: * TI</a> client is called an <i>agent</i>. It is developed in a native language.
383: * A JVM TI agent is deployed in a platform specific manner but it is typically the
384: * platform equivalent of a dynamic library. This method causes the given agent
385: * library to be loaded into the target VM (if not already loaded).
386: * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
387: * as specified in the
388: * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
389: * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
390: * function is invoked even if the agent library was loaded prior to invoking
391: * this method.
392: *
393: * <p> The agent library provided is the absolute path from which to load the
394: * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
395: * is not expanded in the target virtual machine. </p>
396: *
397: * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
398: * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
399: * thrown. The return value from the <code>Agent_OnAttach</code> can then be
400: * obtained by invoking the {@link
401: * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
402: * method on the exception. </p>
403: *
404: * @param agentPath
405: * The full path of the agent library.
406: *
407: * @param options
408: * The options to provide to the <code>Agent_OnAttach</code>
409: * function (can be <code>null</code>).
410: *
411: * @throws AgentLoadException
412: * If the agent library does not exist, or cannot be loaded for
413: * another reason.
414: *
415: * @throws AgentInitializationException
416: * If the <code>Agent_OnAttach</code> function returns an error
417: *
418: * @throws IOException
419: * If an I/O error occurs
420: *
421: * @throws NullPointerException
422: * If <code>agentPath</code> is <code>null</code>.
423: *
424: * @see com.sun.tools.attach.AgentInitializationException#returnValue()
425: */
426: public abstract void loadAgentPath(String agentPath, String options)
427: throws AgentLoadException, AgentInitializationException,
428: IOException;
429:
430: /**
431: * Load a native agent library by full pathname.
432: *
433: * <p> This convenience method works as if by invoking:
434: *
435: * <blockquote><tt>
436: * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null);
437: * </tt></blockquote>
438: *
439: * @param agentPath
440: * The full path to the agent library.
441: *
442: * @throws AgentLoadException
443: * If the agent library does not exist, or cannot be loaded for
444: * another reason.
445: *
446: * @throws AgentInitializationException
447: * If the <code>Agent_OnAttach</code> function returns an error
448: *
449: * @throws IOException
450: * If an I/O error occurs
451: *
452: * @throws NullPointerException
453: * If <code>agentPath</code> is <code>null</code>.
454: */
455: public void loadAgentPath(String agentPath)
456: throws AgentLoadException, AgentInitializationException,
457: IOException {
458: loadAgentPath(agentPath, null);
459: }
460:
461: /**
462: * Loads an agent.
463: *
464: * <p> The agent provided to this method is a path name to a JAR file on the file
465: * system of the target virtual machine. This path is passed to the target virtual
466: * machine where it is interpreted. The target virtual machine attempts to start
467: * the agent as specified by the {@link java.lang.instrument} specification.
468: * That is, the specified JAR file is added to the system class path (of the target
469: * virtual machine), and the <code>agentmain</code> method of the agent class, specified
470: * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This
471: * method completes when the <code>agentmain</code> method completes.
472: *
473: * @param agent
474: * Path to the JAR file containing the agent.
475: *
476: * @param options
477: * The options to provide to the agent's <code>agentmain</code>
478: * method (can be <code>null</code>).
479: *
480: * @throws AgentLoadException
481: * If the agent does not exist, or cannot be started in the manner
482: * specified in the {@link java.lang.instrument} specification.
483: *
484: * @throws AgentInitializationException
485: * If the <code>agentmain</code> throws an exception
486: *
487: * @throws IOException
488: * If an I/O error occurs
489: *
490: * @throws NullPointerException
491: * If <code>agent</code> is <code>null</code>.
492: */
493: public abstract void loadAgent(String agent, String options)
494: throws AgentLoadException, AgentInitializationException,
495: IOException;
496:
497: /**
498: * Loads an agent.
499: *
500: * <p> This convenience method works as if by invoking:
501: *
502: * <blockquote><tt>
503: * {@link #loadAgent(String, String) loadAgent}(agent, null);
504: * </tt></blockquote>
505: *
506: * @param agent
507: * Path to the JAR file containing the agent.
508: *
509: * @throws AgentLoadException
510: * If the agent does not exist, or cannot be started in the manner
511: * specified in the {@link java.lang.instrument} specification.
512: *
513: * @throws AgentInitializationException
514: * If the <code>agentmain</code> throws an exception
515: *
516: * @throws IOException
517: * If an I/O error occurs
518: *
519: * @throws NullPointerException
520: * If <code>agent</code> is <code>null</code>.
521: */
522: public void loadAgent(String agent) throws AgentLoadException,
523: AgentInitializationException, IOException {
524: loadAgent(agent, null);
525: }
526:
527: /**
528: * Returns the current system properties in the target virtual machine.
529: *
530: * <p> This method returns the system properties in the target virtual
531: * machine. Properties whose key or value is not a <tt>String</tt> are
532: * omitted. The method is approximately equivalent to the invocation of the
533: * method {@link java.lang.System#getProperties System.getProperties}
534: * in the target virtual machine except that properties with a key or
535: * value that is not a <tt>String</tt> are not included.
536: *
537: * <p> This method is typically used to decide which agent to load into
538: * the target virtual machine with {@link #loadAgent loadAgent}, or
539: * {@link #loadAgentLibrary loadAgentLibrary}. For example, the
540: * <code>java.home</code> or <code>user.dir</code> properties might be
541: * use to create the path to the agent library or JAR file.
542: *
543: * @return The system properties
544: *
545: * @throws IOException
546: * If an I/O error occurs
547: *
548: * @see java.lang.System#getProperties
549: * @see #loadAgentLibrary
550: * @see #loadAgent
551: */
552: public abstract Properties getSystemProperties() throws IOException;
553:
554: /**
555: * Returns the current <i>agent properties</i> in the target virtual
556: * machine.
557: *
558: * <p> The target virtual machine can maintain a list of properties on
559: * behalf of agents. The manner in which this is done, the names of the
560: * properties, and the types of values that are allowed, is implementation
561: * specific. Agent properties are typically used to store communication
562: * end-points and other agent configuration details. For example, a debugger
563: * agent might create an agent property for its transport address.
564: *
565: * <p> This method returns the agent properties whose key and value is a
566: * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt>
567: * are omitted. If there are no agent properties maintained in the target
568: * virtual machine then an empty property list is returned.
569: *
570: * @return The agent properties
571: *
572: * @throws IOException
573: * If an I/O error occurs
574: */
575: public abstract Properties getAgentProperties() throws IOException;
576:
577: /**
578: * Returns a hash-code value for this VirtualMachine. The hash
579: * code is based upon the VirtualMachine's components, and satifies
580: * the general contract of the {@link java.lang.Object#hashCode()
581: * Object.hashCode} method.
582: *
583: * @return A hash-code value for this virtual machine
584: */
585: public int hashCode() {
586: if (hash != 0) {
587: return hash;
588: }
589: hash = provider.hashCode() * 127 + id.hashCode();
590: return hash;
591: }
592:
593: /**
594: * Tests this VirtualMachine for equality with another object.
595: *
596: * <p> If the given object is not a VirtualMachine then this
597: * method returns <tt>false</tt>. For two VirtualMachines to
598: * be considered equal requires that they both reference the same
599: * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p>
600: *
601: * <p> This method satisfies the general contract of the {@link
602: * java.lang.Object#equals(Object) Object.equals} method. </p>
603: *
604: * @param ob The object to which this object is to be compared
605: *
606: * @return <tt>true</tt> if, and only if, the given object is
607: * a VirtualMachine that is equal to this
608: * VirtualMachine.
609: */
610: public boolean equals(Object ob) {
611: if (ob == this )
612: return true;
613: if (!(ob instanceof VirtualMachine))
614: return false;
615: VirtualMachine other = (VirtualMachine) ob;
616: if (other.provider() != this .provider()) {
617: return false;
618: }
619: if (!other.id().equals(this .id())) {
620: return false;
621: }
622: return true;
623: }
624:
625: /**
626: * Returns the string representation of the <code>VirtualMachine</code>.
627: */
628: public String toString() {
629: return provider.toString() + ": " + id;
630: }
631: }
|