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