History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/com/sun/tools/attach/VirtualMachine.java (1 of 18352 files). Show all

Unified · Split

java/pkg/com/sun/tools/attach/VirtualMachine.java+633−0
@@ -0,0 +1,633 @@
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+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. This method causes the given agent
302+ * library to be loaded into the target VM (if not already loaded).
303+ * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
304+ * as specified in the
305+ * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
306+ * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
307+ * function is invoked even if the agent library was loaded prior to invoking
308+ * this method.
309+ *
310+ * <p> The agent library provided is the name of the agent library. It is interpreted
311+ * in the target virtual machine in an implementation-dependent manner. Typically an
312+ * implementation will expand the library name into an operating system specific file
313+ * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
314+ * <tt>libfoo.so</tt>, and located using the search path specified by the
315+ * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
316+ *
317+ * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
318+ * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
319+ * thrown. The return value from the <code>Agent_OnAttach</code> can then be
320+ * obtained by invoking the {@link
321+ * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
322+ * method on the exception. </p>
323+ *
324+ * @param agentLibrary
325+ * The name of the agent library.
326+ *
327+ * @param options
328+ * The options to provide to the <code>Agent_OnAttach</code>
329+ * function (can be <code>null</code>).
330+ *
331+ * @throws AgentLoadException
332+ * If the agent library does not exist, or cannot be loaded for
333+ * another reason.
334+ *
335+ * @throws AgentInitializationException
336+ * If the <code>Agent_OnAttach</code> function returns an error
337+ *
338+ * @throws IOException
339+ * If an I/O error occurs
340+ *
341+ * @throws NullPointerException
342+ * If <code>agentLibrary</code> is <code>null</code>.
343+ *
344+ * @see com.sun.tools.attach.AgentInitializationException#returnValue()
345+ */
346+ public abstract void loadAgentLibrary(String agentLibrary, String options)
347+ throws AgentLoadException, AgentInitializationException, IOException;
348+
349+ /**
350+ * Loads an agent library.
351+ *
352+ * <p> This convenience method works as if by invoking:
353+ *
354+ * <blockquote><tt>
355+ * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary,&nbsp;null);
356+ * </tt></blockquote>
357+ *
358+ * @param agentLibrary
359+ * The name of the agent library.
360+ *
361+ * @throws AgentLoadException
362+ * If the agent library does not exist, or cannot be loaded for
363+ * another reason.
364+ *
365+ * @throws AgentInitializationException
366+ * If the <code>Agent_OnAttach</code> function returns an error
367+ *
368+ * @throws IOException
369+ * If an I/O error occurs
370+ *
371+ * @throws NullPointerException
372+ * If <code>agentLibrary</code> is <code>null</code>.
373+ */
374+ public void loadAgentLibrary(String agentLibrary)
375+ throws AgentLoadException, AgentInitializationException, IOException
376+ {
377+ loadAgentLibrary(agentLibrary, null);
378+ }
379+
380+ /**
381+ * Load a native agent library by full pathname.
382+ *
383+ * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
384+ * TI</a> client is called an <i>agent</i>. It is developed in a native language.
385+ * A JVM TI agent is deployed in a platform specific manner but it is typically the
386+ * platform equivalent of a dynamic library. This method causes the given agent
387+ * library to be loaded into the target VM (if not already loaded).
388+ * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
389+ * as specified in the
390+ * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
391+ * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
392+ * function is invoked even if the agent library was loaded prior to invoking
393+ * this method.
394+ *
395+ * <p> The agent library provided is the absolute path from which to load the
396+ * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
397+ * is not expanded in the target virtual machine. </p>
398+ *
399+ * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
400+ * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
401+ * thrown. The return value from the <code>Agent_OnAttach</code> can then be
402+ * obtained by invoking the {@link
403+ * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
404+ * method on the exception. </p>
405+ *
406+ * @param agentPath
407+ * The full path of the agent library.
408+ *
409+ * @param options
410+ * The options to provide to the <code>Agent_OnAttach</code>
411+ * function (can be <code>null</code>).
412+ *
413+ * @throws AgentLoadException
414+ * If the agent library does not exist, or cannot be loaded for
415+ * another reason.
416+ *
417+ * @throws AgentInitializationException
418+ * If the <code>Agent_OnAttach</code> function returns an error
419+ *
420+ * @throws IOException
421+ * If an I/O error occurs
422+ *
423+ * @throws NullPointerException
424+ * If <code>agentPath</code> is <code>null</code>.
425+ *
426+ * @see com.sun.tools.attach.AgentInitializationException#returnValue()
427+ */
428+ public abstract void loadAgentPath(String agentPath, String options)
429+ throws AgentLoadException, AgentInitializationException, IOException;
430+
431+ /**
432+ * Load a native agent library by full pathname.
433+ *
434+ * <p> This convenience method works as if by invoking:
435+ *
436+ * <blockquote><tt>
437+ * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary,&nbsp;null);
438+ * </tt></blockquote>
439+ *
440+ * @param agentPath
441+ * The full path to the agent library.
442+ *
443+ * @throws AgentLoadException
444+ * If the agent library does not exist, or cannot be loaded for
445+ * another reason.
446+ *
447+ * @throws AgentInitializationException
448+ * If the <code>Agent_OnAttach</code> function returns an error
449+ *
450+ * @throws IOException
451+ * If an I/O error occurs
452+ *
453+ * @throws NullPointerException
454+ * If <code>agentPath</code> is <code>null</code>.
455+ */
456+ public void loadAgentPath(String agentPath)
457+ throws AgentLoadException, AgentInitializationException, IOException
458+ {
459+ loadAgentPath(agentPath, null);
460+ }
461+
462+
463+ /**
464+ * Loads an agent.
465+ *
466+ * <p> The agent provided to this method is a path name to a JAR file on the file
467+ * system of the target virtual machine. This path is passed to the target virtual
468+ * machine where it is interpreted. The target virtual machine attempts to start
469+ * the agent as specified by the {@link java.lang.instrument} specification.
470+ * That is, the specified JAR file is added to the system class path (of the target
471+ * virtual machine), and the <code>agentmain</code> method of the agent class, specified
472+ * by the <code>Agent-Class</code> attribute in the JAR manifest, is invoked. This
473+ * method completes when the <code>agentmain</code> method completes.
474+ *
475+ * @param agent
476+ * Path to the JAR file containing the agent.
477+ *
478+ * @param options
479+ * The options to provide to the agent's <code>agentmain</code>
480+ * method (can be <code>null</code>).
481+ *
482+ * @throws AgentLoadException
483+ * If the agent does not exist, or cannot be started in the manner
484+ * specified in the {@link java.lang.instrument} specification.
485+ *
486+ * @throws AgentInitializationException
487+ * If the <code>agentmain</code> throws an exception
488+ *
489+ * @throws IOException
490+ * If an I/O error occurs
491+ *
492+ * @throws NullPointerException
493+ * If <code>agent</code> is <code>null</code>.
494+ */
495+ public abstract void loadAgent(String agent, String options)
496+ throws AgentLoadException, AgentInitializationException, IOException;
497+
498+ /**
499+ * Loads an agent.
500+ *
501+ * <p> This convenience method works as if by invoking:
502+ *
503+ * <blockquote><tt>
504+ * {@link #loadAgent(String, String) loadAgent}(agent,&nbsp;null);
505+ * </tt></blockquote>
506+ *
507+ * @param agent
508+ * Path to the JAR file containing the agent.
509+ *
510+ * @throws AgentLoadException
511+ * If the agent does not exist, or cannot be started in the manner
512+ * specified in the {@link java.lang.instrument} specification.
513+ *
514+ * @throws AgentInitializationException
515+ * If the <code>agentmain</code> throws an exception
516+ *
517+ * @throws IOException
518+ * If an I/O error occurs
519+ *
520+ * @throws NullPointerException
521+ * If <code>agent</code> is <code>null</code>.
522+ */
523+ public void loadAgent(String agent)
524+ throws AgentLoadException, AgentInitializationException, IOException
525+ {
526+ loadAgent(agent, null);
527+ }
528+
529+ /**
530+ * Returns the current system properties in the target virtual machine.
531+ *
532+ * <p> This method returns the system properties in the target virtual
533+ * machine. Properties whose key or value is not a <tt>String</tt> are
534+ * omitted. The method is approximately equivalent to the invocation of the
535+ * method {@link java.lang.System#getProperties System.getProperties}
536+ * in the target virtual machine except that properties with a key or
537+ * value that is not a <tt>String</tt> are not included.
538+ *
539+ * <p> This method is typically used to decide which agent to load into
540+ * the target virtual machine with {@link #loadAgent loadAgent}, or
541+ * {@link #loadAgentLibrary loadAgentLibrary}. For example, the
542+ * <code>java.home</code> or <code>user.dir</code> properties might be
543+ * use to create the path to the agent library or JAR file.
544+ *
545+ * @return The system properties
546+ *
547+ * @throws IOException
548+ * If an I/O error occurs
549+ *
550+ * @see java.lang.System#getProperties
551+ * @see #loadAgentLibrary
552+ * @see #loadAgent
553+ */
554+ public abstract Properties getSystemProperties() throws IOException;
555+
556+ /**
557+ * Returns the current <i>agent properties</i> in the target virtual
558+ * machine.
559+ *
560+ * <p> The target virtual machine can maintain a list of properties on
561+ * behalf of agents. The manner in which this is done, the names of the
562+ * properties, and the types of values that are allowed, is implementation
563+ * specific. Agent properties are typically used to store communication
564+ * end-points and other agent configuration details. For example, a debugger
565+ * agent might create an agent property for its transport address.
566+ *
567+ * <p> This method returns the agent properties whose key and value is a
568+ * <tt>String</tt>. Properties whose key or value is not a <tt>String</tt>
569+ * are omitted. If there are no agent properties maintained in the target
570+ * virtual machine then an empty property list is returned.
571+ *
572+ * @return The agent properties
573+ *
574+ * @throws IOException
575+ * If an I/O error occurs
576+ */
577+ public abstract Properties getAgentProperties() throws IOException;
578+
579+ /**
580+ * Returns a hash-code value for this VirtualMachine. The hash
581+ * code is based upon the VirtualMachine's components, and satifies
582+ * the general contract of the {@link java.lang.Object#hashCode()
583+ * Object.hashCode} method.
584+ *
585+ * @return A hash-code value for this virtual machine
586+ */
587+ public int hashCode() {
588+ if (hash != 0) {
589+ return hash;
590+ }
591+ hash = provider.hashCode() * 127 + id.hashCode();
592+ return hash;
593+ }
594+
595+ /**
596+ * Tests this VirtualMachine for equality with another object.
597+ *
598+ * <p> If the given object is not a VirtualMachine then this
599+ * method returns <tt>false</tt>. For two VirtualMachines to
600+ * be considered equal requires that they both reference the same
601+ * provider, and their {@link VirtualMachineDescriptor#id() identifiers} are equal. </p>
602+ *
603+ * <p> This method satisfies the general contract of the {@link
604+ * java.lang.Object#equals(Object) Object.equals} method. </p>
605+ *
606+ * @param ob The object to which this object is to be compared
607+ *
608+ * @return <tt>true</tt> if, and only if, the given object is
609+ * a VirtualMachine that is equal to this
610+ * VirtualMachine.
611+ */
612+ public boolean equals(Object ob) {
613+ if (ob == this)
614+ return true;
615+ if (!(ob instanceof VirtualMachine))
616+ return false;
617+ VirtualMachine other = (VirtualMachine)ob;
618+ if (other.provider() != this.provider()) {
619+ return false;
620+ }
621+ if (!other.id().equals(this.id())) {
622+ return false;
623+ }
624+ return true;
625+ }
626+
627+ /**
628+ * Returns the string representation of the <code>VirtualMachine</code>.
629+ */
630+ public String toString() {
631+ return provider.toString() + ": " + id;
632+ }
633+}