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 either in a dynamic library or statically linked into the VM 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 public abstract class VirtualMachine {
106 private AttachProvider provider;
107 private String id;
108 private volatile int hash; // 0 => not computed
109
110 /**
111 * Initializes a new instance of this class.
112 *
113 * @param provider
114 * The attach provider creating this class.
115 * @param id
116 * The abstract identifier that identifies the Java virtual machine.
117 *
118 * @throws NullPointerException
119 * If <code>provider</code> or <code>id</code> is <code>null</code>.
120 */
121 protected VirtualMachine(AttachProvider provider, String id) {
122 if (provider == null) {
123 throw new NullPointerException("provider cannot be null");
124 }
125 if (id == null) {
126 throw new NullPointerException("id cannot be null");
127 }
128 this.provider = provider;
129 this.id = id;
130 }
131
132 /**
133 * Return a list of Java virtual machines.
134 *
135 * <p> This method returns a list of Java {@link
136 * com.sun.tools.attach.VirtualMachineDescriptor} elements.
137 * The list is an aggregation of the virtual machine
138 * descriptor lists obtained by invoking the {@link
139 * com.sun.tools.attach.spi.AttachProvider#listVirtualMachines
140 * listVirtualMachines} method of all installed
141 * {@link com.sun.tools.attach.spi.AttachProvider attach providers}.
142 * If there are no Java virtual machines known to any provider
143 * then an empty list is returned.
144 *
145 * @return The list of virtual machine descriptors.
146 */
147 public static List<VirtualMachineDescriptor> list() {
148 ArrayList<VirtualMachineDescriptor> l =
149 new ArrayList<VirtualMachineDescriptor>();
150 List<AttachProvider> providers = AttachProvider.providers();
151 for (AttachProvider provider: providers) {
152 l.addAll(provider.listVirtualMachines());
153 }
154 return l;
155 }
156
157 /**
158 * Attaches to a Java virtual machine.
159 *
160 * <p> This method obtains the list of attach providers by invoking the
161 * {@link com.sun.tools.attach.spi.AttachProvider#providers()
162 * AttachProvider.providers()} method. It then iterates overs the list
163 * and invokes each provider's {@link
164 * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(java.lang.String)
165 * attachVirtualMachine} method in turn. If a provider successfully
166 * attaches then the iteration terminates, and the VirtualMachine created
167 * by the provider that successfully attached is returned by this method.
168 * If the <code>attachVirtualMachine</code> method of all providers throws
169 * {@link com.sun.tools.attach.AttachNotSupportedException AttachNotSupportedException}
170 * then this method also throws <code>AttachNotSupportedException</code>.
171 * This means that <code>AttachNotSupportedException</code> is thrown when
172 * the identifier provided to this method is invalid, or the identifier
173 * corresponds to a Java virtual machine that does not exist, or none
174 * of the providers can attach to it. This exception is also thrown if
175 * {@link com.sun.tools.attach.spi.AttachProvider#providers()
176 * AttachProvider.providers()} returns an empty list. </p>
177 *
178 * @param id
179 * The abstract identifier that identifies the Java virtual machine.
180 *
181 * @return A VirtualMachine representing the target VM.
182 *
183 * @throws SecurityException
184 * If a security manager has been installed and it denies
185 * {@link com.sun.tools.attach.AttachPermission AttachPermission}
186 * <tt>("attachVirtualMachine")</tt>, or another permission
187 * required by the implementation.
188 *
189 * @throws AttachNotSupportedException
190 * If the <code>attachVirtualmachine</code> method of all installed
191 * providers throws <code>AttachNotSupportedException</code>, or
192 * there aren't any providers installed.
193 *
194 * @throws IOException
195 * If an I/O error occurs
196 *
197 * @throws NullPointerException
198 * If <code>id</code> is <code>null</code>.
199 */
200 public static VirtualMachine attach(String id)
201 throws AttachNotSupportedException, IOException
202 {
203 if (id == null) {
204 throw new NullPointerException("id cannot be null");
205 }
206 List<AttachProvider> providers = AttachProvider.providers();
207 if (providers.size() == 0) {
208 throw new AttachNotSupportedException("no providers installed");
209 }
210 AttachNotSupportedException lastExc = null;
211 for (AttachProvider provider: providers) {
212 try {
213 return provider.attachVirtualMachine(id);
214 } catch (AttachNotSupportedException x) {
215 lastExc = x;
216 }
217 }
218 throw lastExc;
219 }
220
221 /**
222 * Attaches to a Java virtual machine.
223 *
224 * <p> This method first invokes the {@link
225 * com.sun.tools.attach.VirtualMachineDescriptor#provider() provider()} method
226 * of the given virtual machine descriptor to obtain the attach provider. It
227 * then invokes the attach provider's {@link
228 * com.sun.tools.attach.spi.AttachProvider#attachVirtualMachine(VirtualMachineDescriptor)
229 * attachVirtualMachine} to attach to the target VM.
230 *
231 * @param vmd
232 * The virtual machine descriptor.
233 *
234 * @return A VirtualMachine representing the target VM.
235 *
236 * @throws SecurityException
237 * If a security manager has been installed and it denies
238 * {@link com.sun.tools.attach.AttachPermission AttachPermission}
239 * <tt>("attachVirtualMachine")</tt>, or another permission
240 * required by the implementation.
241 *
242 * @throws AttachNotSupportedException
243 * If the attach provider's <code>attachVirtualmachine</code>
244 * throws <code>AttachNotSupportedException</code>.
245 *
246 * @throws IOException
247 * If an I/O error occurs
248 *
249 * @throws NullPointerException
250 * If <code>vmd</code> is <code>null</code>.
251 */
252 public static VirtualMachine attach(VirtualMachineDescriptor vmd)
253 throws AttachNotSupportedException, IOException
254 {
255 return vmd.provider().attachVirtualMachine(vmd);
256 }
257
258 /**
259 * Detach from the virtual machine.
260 *
261 * <p> After detaching from the virtual machine, any further attempt to invoke
262 * operations on that virtual machine will cause an {@link java.io.IOException
263 * IOException} to be thrown. If an operation (such as {@link #loadAgent
264 * loadAgent} for example) is in progress when this method is invoked then
265 * the behaviour is implementation dependent. In other words, it is
266 * implementation specific if the operation completes or throws
267 * <tt>IOException</tt>.
268 *
269 * <p> If already detached from the virtual machine then invoking this
270 * method has no effect. </p>
271 *
272 * @throws IOException
273 * If an I/O error occurs
274 */
275 public abstract void detach() throws IOException;
276
277 /**
278 * Returns the provider that created this virtual machine.
279 *
280 * @return The provider that created this virtual machine.
281 */
282 public final AttachProvider provider() {
283 return provider;
284 }
285
286 /**
287 * Returns the identifier for this Java virtual machine.
288 *
289 * @return The identifier for this Java virtual machine.
290 */
291 public final String id() {
292 return id;
293 }
294
295 /**
296 * Loads an agent library.
297 *
298 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
299 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
300 * A JVM TI agent is deployed in a platform specific manner but it is typically the
301 * platform equivalent of a dynamic library. Alternatively, it may be statically linked into the VM.
302 * This method causes the given agent library to be loaded into the target
303 * VM (if not already loaded or if not statically linked into the VM).
304 * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
305 * or, for a statically linked agent named 'L', the <code>Agent_OnAttach_L</code> function
306 * as specified in the
307 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
308 * Interface</a> specification. Note that the <code>Agent_OnAttach[_L]</code>
309 * function is invoked even if the agent library was loaded prior to invoking
310 * this method.
311 *
312 * <p> The agent library provided is the name of the agent library. It is interpreted
313 * in the target virtual machine in an implementation-dependent manner. Typically an
314 * implementation will expand the library name into an operating system specific file
315 * name. For example, on UNIX systems, the name <tt>L</tt> might be expanded to
316 * <tt>libL.so</tt>, and located using the search path specified by the
317 * <tt>LD_LIBRARY_PATH</tt> environment variable. If the agent named 'L' is
318 * statically linked into the VM then the VM must export a function named
319 * <code>Agent_OnAttach_L</code>.</p>
320 *
321 * <p> If the <code>Agent_OnAttach[_L]</code> function in the agent library returns
322 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
323 * thrown. The return value from the <code>Agent_OnAttach[_L]</code> can then be
324 * obtained by invoking the {@link
325 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
326 * method on the exception. </p>
327 *
328 * @param agentLibrary
329 * The name of the agent library.
330 *
331 * @param options
332 * The options to provide to the <code>Agent_OnAttach[_L]</code>
333 * function (can be <code>null</code>).
334 *
335 * @throws AgentLoadException
336 * If the agent library does not exist, the agent library is not
337 * statically linked with the VM, or the agent library cannot be
338 * loaded for another reason.
339 *
340 * @throws AgentInitializationException
341 * If the <code>Agent_OnAttach</code> function returns an error
342 * or, for a statically linked agent named 'L', if the
343 * <code>Agent_OnAttach_L</code> function returns
344 * an error.
345 *
346 * @throws IOException
347 * If an I/O error occurs
348 *
349 * @throws NullPointerException
350 * If <code>agentLibrary</code> is <code>null</code>.
351 *
352 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
353 */
354 public abstract void loadAgentLibrary(String agentLibrary, String options)
355 throws AgentLoadException, AgentInitializationException, IOException;
356
357 /**
358 * Loads an agent library.
359 *
360 * <p> This convenience method works as if by invoking:
361 *
362 * <blockquote><tt>
363 * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
364 * </tt></blockquote>
365 *
366 * @param agentLibrary
367 * The name of the agent library.
368 *
369 * @throws AgentLoadException
370 * If the agent library does not exist, the agent library is not
371 * statically linked with the VM, or the agent library cannot be
372 * loaded for another reason.
373 *
374 * @throws AgentInitializationException
375 * If the <code>Agent_OnAttach</code> function returns an error
376 * or, for a statically linked agent named 'L', if the
377 * <code>Agent_OnAttach_L</code> function returns
378 * an error.
379 *
380 * @throws IOException
381 * If an I/O error occurs
382 *
383 * @throws NullPointerException
384 * If <code>agentLibrary</code> is <code>null</code>.
385 */
386 public void loadAgentLibrary(String agentLibrary)
387 throws AgentLoadException, AgentInitializationException, IOException
388 {
389 loadAgentLibrary(agentLibrary, null);
390 }
391
392 /**
393 * Load a native agent library by full pathname.
394 *
395 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
396 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
397 * A JVM TI agent is deployed in a platform specific manner but it is typically the
398 * platform equivalent of a dynamic library. Alternatively, the native
399 * library specified by the agentPath parameter may be statically
400 * linked with the VM. The parsing of the agentPath paramter into
401 * a statically linked library name is done in a platform
402 * specific manner in the VM. For example, in UNIX, an agentPath paramter
403 * of <code>/a/b/libL.so</code> would name a library 'L'.
404 *
405 * See the JVM TI Specification for more details.
406 *
407 * This method causes the given agent library to be loaded into the target
408 * VM (if not already loaded or if not statically linked into the VM).
409 * It then causes the target VM to invoke the <code>Agent_OnAttach</code>
410 * function or, for a statically linked agent named 'L', the
411 * <code>Agent_OnAttach_L</code> function as specified in the
412 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
413 * Interface</a> specification.
414 * Note that the <code>Agent_OnAttach[_L]</code>
415 * function is invoked even if the agent library was loaded prior to invoking
416 * this method.
417 *
418 * <p> The agent library provided is the absolute path from which to load the
419 * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
420 * is not expanded in the target virtual machine. </p>
421 *
422 * <p> If the <code>Agent_OnAttach[_L]</code> function in the agent library returns
423 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
424 * thrown. The return value from the <code>Agent_OnAttach[_L]</code> can then be
425 * obtained by invoking the {@link
426 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
427 * method on the exception. </p>
428 *
429 * @param agentPath
430 * The full path of the agent library.
431 *
432 * @param options
433 * The options to provide to the <code>Agent_OnAttach[_L]</code>
434 * function (can be <code>null</code>).
435 *
436 * @throws AgentLoadException
437 * If the agent library does not exist, the agent library is not
438 * statically linked with the VM, or the agent library cannot be
439 * loaded for another reason.
440 *
441 * @throws AgentInitializationException
442 * If the <code>Agent_OnAttach</code> function returns an error
443 * or, for a statically linked agent named 'L', if the
444 * <code>Agent_OnAttach_L</code> function returns an error
445 *
446 * @throws IOException
447 * If an I/O error occurs
448 *
449 * @throws NullPointerException
450 * If <code>agentPath</code> is <code>null</code>.
451 *
452 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
453 */
454 public abstract void loadAgentPath(String agentPath, String options)
455 throws AgentLoadException, AgentInitializationException, IOException;
456
457 /**
458 * Load a native agent library by full pathname.
459 *
460 * <p> This convenience method works as if by invoking:
461 *
462 * <blockquote><tt>
463 * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null);
464 * </tt></blockquote>
465 *
466 * @param agentPath
467 * The full path to the agent library.
468 *
469 * @throws AgentLoadException
470 * If the agent library does not exist, the agent library is not
471 * statically linked with the VM, or the agent library cannot be
472 * loaded for another reason.
473 *
474 * @throws AgentInitializationException
475 * If the <code>Agent_OnAttach</code> function returns an error
476 * or, for a statically linked agent named 'L', if the
477 * <code>Agent_OnAttach_L</code> function returns
478 * an error.
479 *
480 * @throws IOException
481 * If an I/O error occurs
482 *
483 * @throws NullPointerException
484 * If <code>agentPath</code> is <code>null</code>.
485 */
486 public void loadAgentPath(String agentPath)
487 throws AgentLoadException, AgentInitializationException, IOException
488 {
489 loadAgentPath(agentPath, null);
490 }
491
492
493 /**
494 * Loads an agent.
495 *
496 * <p> The agent provided to this method is a path name to a JAR file on the file
497 * system of the target virtual machine. This path is passed to the target virtual
498 * machine where it is interpreted. The target virtual machine attempts to start
499 * the agent as specified by the {@link java.lang.instrument} specification.
500 * That is, the specified JAR file is added to the system class path (of the target
501 * virtual machine), and the <code>agentmain</code> method of the agent class, specified
502 * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This
503 * method completes when the <code>agentmain</code> method completes.
504 *
505 * @param agent
506 * Path to the JAR file containing the agent.
507 *
508 * @param options
509 * The options to provide to the agent's <code>agentmain</code>
510 * method (can be <code>null</code>).
511 *
512 * @throws AgentLoadException
513 * If the agent does not exist, or cannot be started in the manner
514 * specified in the {@link java.lang.instrument} specification.
515 *
516 * @throws AgentInitializationException
517 * If the <code>agentmain</code> throws an exception
518 *
519 * @throws IOException
520 * If an I/O error occurs
521 *
522 * @throws NullPointerException
523 * If <code>agent</code> is <code>null</code>.
524 */
525 public abstract void loadAgent(String agent, String options)
526 throws AgentLoadException, AgentInitializationException, IOException;
527
528 /**
529 * Loads an agent.
530 *
531 * <p> This convenience method works as if by invoking:
532 *
533 * <blockquote><tt>
534 * {@link #loadAgent(String, String) loadAgent}(agent, null);
535 * </tt></blockquote>
536 *
537 * @param agent
538 * Path to the JAR file containing the agent.
539 *
540 * @throws AgentLoadException
541 * If the agent does not exist, or cannot be started in the manner
542 * specified in the {@link java.lang.instrument} specification.
543 *
544 * @throws AgentInitializationException
545 * If the <code>agentmain</code> throws an exception
546 *
547 * @throws IOException
548 * If an I/O error occurs
549 *
550 * @throws NullPointerException
551 * If <code>agent</code> is <code>null</code>.
552 */
553 public void loadAgent(String agent)
554 throws AgentLoadException, AgentInitializationException, IOException
555 {
556 loadAgent(agent, null);
557 }
558
559 /**
560 * Returns the current system properties in the target virtual machine.
561 *
562 * <p> This method returns the system properties in the target virtual
563 * machine. Properties whose key or value is not a <tt>String</tt> are
564 * omitted. The method is approximately equivalent to the invocation of the
565 * method {@link java.lang.System#getProperties System.getProperties}
566 * in the target virtual machine except that properties with a key or
567 * value that is not a <tt>String</tt> are not included.
568 *
569 * <p> This method is typically used to decide which agent to load into
570 * the target virtual machine with {@link #loadAgent loadAgent}, or
571 * {@link #loadAgentLibrary loadAgentLibrary}. For example, the
572 * <code>java.home</code> or <code>user.dir</code> properties might be
573 * use to create the path to the agent library or JAR file.
574 *
575 * @return The system properties
576 *
577 * @throws IOException
578 * If an I/O error occurs
579 *
580 * @see java.lang.System#getProperties
581 * @see #loadAgentLibrary
582 * @see #loadAgent
583 */
584 public abstract Properties getSystemProperties() throws IOException;
585
586 /**
587 * Returns the current <i>agent properties</i> in the target virtual
588 * machine.
589 *
590 * <p> The target virtual machine can maintain a list of properties on
591 * behalf of agents. The manner in which this is done, the names of the
592 * properties, and the types of values that are allowed, is implementation
593 * specific. Agent properties are typically used to store communication
594 * end-points and other agent configuration details. For example, a debugger
595 * agent might create an agent property for its transport address.
596 *
597 * <p> This method returns the agent properties whose key and value is a
598 * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt>
599 * are omitted. If there are no agent properties maintained in the target
600 * virtual machine then an empty property list is returned.
601 *
602 * @return The agent properties
603 *
604 * @throws IOException
605 * If an I/O error occurs
606 */
607 public abstract Properties getAgentProperties() throws IOException;
608
609 /**
610 * Returns a hash-code value for this VirtualMachine. The hash
611 * code is based upon the VirtualMachine's components, and satifies
612 * the general contract of the {@link java.lang.Object#hashCode()
613 * Object.hashCode} method.
614 *
615 * @return A hash-code value for this virtual machine
616 */
617 public int hashCode() {
618 if (hash != 0) {
619 return hash;
620 }
621 hash = provider.hashCode() * 127 + id.hashCode();
622 return hash;
623 }
624
625 /**
626 * Tests this VirtualMachine for equality with another object.
627 *
628 * <p> If the given object is not a VirtualMachine then this
629 * method returns <tt>false</tt>. For two VirtualMachines to
630 * be considered equal requires that they both reference the same
631 * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p>
632 *
633 * <p> This method satisfies the general contract of the {@link
634 * java.lang.Object#equals(Object) Object.equals} method. </p>
635 *
636 * @param ob The object to which this object is to be compared
637 *
638 * @return <tt>true</tt> if, and only if, the given object is
639 * a VirtualMachine that is equal to this
640 * VirtualMachine.
641 */
642 public boolean equals(Object ob) {
643 if (ob == this)
644 return true;
645 if (!(ob instanceof VirtualMachine))
646 return false;
647 VirtualMachine other = (VirtualMachine)ob;
648 if (other.provider() != this.provider()) {
649 return false;
650 }
651 if (!other.id().equals(this.id())) {
652 return false;
653 }
654 return true;
655 }
656
657 /**
658 * Returns the string representation of the <code>VirtualMachine</code>.
659 */
660 public String toString() {
661 return provider.toString() + ": " + id;
662 }
663 }