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
30 /**
31 * Describes a Java virtual machine.
32 *
33 * <p> A <code>VirtualMachineDescriptor</code> is a container class used to
34 * describe a Java virtual machine. It encapsulates an identifier that identifies
35 * a target virtual machine, and a reference to the {@link
36 * com.sun.tools.attach.spi.AttachProvider AttachProvider} that should be used
37 * when attempting to attach to the virtual machine. The identifier is
38 * implementation-dependent but is typically the process identifier (or pid)
39 * environments where each Java virtual machine runs in its own operating system
40 * process. </p>
41 *
42 * <p> A <code>VirtualMachineDescriptor</code> also has a {@link #displayName() displayName}.
43 * The display name is typically a human readable string that a tool might
44 * display to a user. For example, a tool that shows a list of Java
45 * virtual machines running on a system might use the display name rather
46 * than the identifier. A <code>VirtualMachineDescriptor</code> may be
47 * created without a <i>display name</i>. In that case the identifier is
48 * used as the <i>display name</i>.
49 *
50 * <p> <code>VirtualMachineDescriptor</code> instances are typically created by
51 * invoking the {@link com.sun.tools.attach.VirtualMachine#list VirtualMachine.list()}
52 * method. This returns the complete list of descriptors to describe the
53 * Java virtual machines known to all installed {@link
54 * com.sun.tools.attach.spi.AttachProvider attach providers}.
55 *
56 * @since 1.6
57 */
58 @jdk.Supported
59 public class VirtualMachineDescriptor {
60
61 private AttachProvider provider;
62 private String id;
63 private String displayName;
64
65 private volatile int hash; // 0 => not computed
66
67 /**
68 * Creates a virtual machine descriptor from the given components.
69 *
70 * @param provider The AttachProvider to attach to the Java virtual machine.
71 * @param id The virtual machine identifier.
72 * @param displayName The display name.
73 *
74 * @throws NullPointerException
75 * If any of the arguments are <code>null</code>
76 */
77 public VirtualMachineDescriptor(AttachProvider provider, String id, String displayName) {
78 if (provider == null) {
79 throw new NullPointerException("provider cannot be null");
80 }
81 if (id == null) {
82 throw new NullPointerException("identifier cannot be null");
83 }
84 if (displayName == null) {
85 throw new NullPointerException("display name cannot be null");
86 }
87 this.provider = provider;
88 this.id = id;
89 this.displayName = displayName;
90 }
91
92 /**
93 * Creates a virtual machine descriptor from the given components.
94 *
95 * <p> This convenience constructor works as if by invoking the
96 * three-argument constructor as follows:
97 *
98 * <blockquote><tt>
99 * new {@link #VirtualMachineDescriptor(AttachProvider, String, String)
100 * VirtualMachineDescriptor}(provider, id, id);
101 * </tt></blockquote>
102 *
103 * <p> That is, it creates a virtual machine descriptor such that
104 * the <i>display name</i> is the same as the virtual machine
105 * identifier.
106 *
107 * @param provider The AttachProvider to attach to the Java virtual machine.
108 * @param id The virtual machine identifier.
109 *
110 * @throws NullPointerException
111 * If <tt>provider</tt> or <tt>id</tt> is <tt>null</tt>.
112 */
113 public VirtualMachineDescriptor(AttachProvider provider, String id) {
114 this(provider, id, id);
115 }
116
117 /**
118 * Return the <code>AttachProvider</code> that this descriptor references.
119 *
120 * @return The <code>AttachProvider</code> that this descriptor references.
121 */
122 public AttachProvider provider() {
123 return provider;
124 }
125
126 /**
127 * Return the identifier component of this descriptor.
128 *
129 * @return The identifier component of this descriptor.
130 */
131 public String id() {
132 return id;
133 }
134
135 /**
136 * Return the <i>display name</i> component of this descriptor.
137 *
138 * @return The display name component of this descriptor.
139 */
140 public String displayName() {
141 return displayName;
142 }
143
144 /**
145 * Returns a hash-code value for this VirtualMachineDescriptor. The hash
146 * code is based upon the descriptor's components, and satifies
147 * the general contract of the {@link java.lang.Object#hashCode()
148 * Object.hashCode} method.
149 *
150 * @return A hash-code value for this descriptor.
151 */
152 public int hashCode() {
153 if (hash != 0) {
154 return hash;
155 }
156 hash = provider.hashCode() * 127 + id.hashCode();
157 return hash;
158 }
159
160 /**
161 * Tests this VirtualMachineDescriptor for equality with another object.
162 *
163 * <p> If the given object is not a VirtualMachineDescriptor then this
164 * method returns <tt>false</tt>. For two VirtualMachineDescriptors to
165 * be considered equal requires that they both reference the same
166 * provider, and their {@link #id() identifiers} are equal. </p>
167 *
168 * <p> This method satisfies the general contract of the {@link
169 * java.lang.Object#equals(Object) Object.equals} method. </p>
170 *
171 * @param ob The object to which this object is to be compared
172 *
173 * @return <tt>true</tt> if, and only if, the given object is
174 * a VirtualMachineDescriptor that is equal to this
175 * VirtualMachineDescriptor.
176 */
177 public boolean equals(Object ob) {
178 if (ob == this)
179 return true;
180 if (!(ob instanceof VirtualMachineDescriptor))
181 return false;
182 VirtualMachineDescriptor other = (VirtualMachineDescriptor)ob;
183 if (other.provider() != this.provider()) {
184 return false;
185 }
186 if (!other.id().equals(this.id())) {
187 return false;
188 }
189 return true;
190 }
191
192 /**
193 * Returns the string representation of the <code>VirtualMachineDescriptor</code>.
194 */
195 public String toString() {
196 String s = provider.toString() + ": " + id;
197 if (displayName != id) {
198 s += " " + displayName;
199 }
200 return s;
201 }
202
203
204 }