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:
030: /**
031: * Describes a Java virtual machine.
032: *
033: * <p> A <code>VirtualMachineDescriptor</code> is a container class used to
034: * describe a Java virtual machine. It encapsulates an identifier that identifies
035: * a target virtual machine, and a reference to the {@link
036: * com.sun.tools.attach.spi.AttachProvider AttachProvider} that should be used
037: * when attempting to attach to the virtual machine. The identifier is
038: * implementation-dependent but is typically the process identifier (or pid)
039: * environments where each Java virtual machine runs in its own operating system
040: * process. </p>
041: *
042: * <p> A <code>VirtualMachineDescriptor</code> also has a {@link #displayName() displayName}.
043: * The display name is typically a human readable string that a tool might
044: * display to a user. For example, a tool that shows a list of Java
045: * virtual machines running on a system might use the display name rather
046: * than the identifier. A <code>VirtualMachineDescriptor</code> may be
047: * created without a <i>display name</i>. In that case the identifier is
048: * used as the <i>display name</i>.
049: *
050: * <p> <code>VirtualMachineDescriptor</code> instances are typically created by
051: * invoking the {@link com.sun.tools.attach.VirtualMachine#list VirtualMachine.list()}
052: * method. This returns the complete list of descriptors to describe the
053: * Java virtual machines known to all installed {@link
054: * com.sun.tools.attach.spi.AttachProvider attach providers}.
055: *
056: * @since 1.6
057: */
058: public class VirtualMachineDescriptor {
059:
060: private AttachProvider provider;
061: private String id;
062: private String displayName;
063:
064: private volatile int hash; // 0 => not computed
065:
066: /**
067: * Creates a virtual machine descriptor from the given components.
068: *
069: * @param provider The AttachProvider to attach to the Java virtual machine.
070: * @param id The virtual machine identifier.
071: * @param displayName The display name.
072: *
073: * @throws NullPointerException
074: * If any of the arguments are <code>null</code>
075: */
076: public VirtualMachineDescriptor(AttachProvider provider, String id,
077: String displayName) {
078: if (provider == null) {
079: throw new NullPointerException("provider cannot be null");
080: }
081: if (id == null) {
082: throw new NullPointerException("identifier cannot be null");
083: }
084: if (displayName == null) {
085: throw new NullPointerException(
086: "display name cannot be null");
087: }
088: this .provider = provider;
089: this .id = id;
090: this .displayName = displayName;
091: }
092:
093: /**
094: * Creates a virtual machine descriptor from the given components.
095: *
096: * <p> This convenience constructor works as if by invoking the
097: * three-argument constructor as follows:
098: *
099: * <blockquote><tt>
100: * new {@link #VirtualMachineDescriptor(AttachProvider, String, String)
101: * VirtualMachineDescriptor}(provider, id, id);
102: * </tt></blockquote>
103: *
104: * <p> That is, it creates a virtual machine descriptor such that
105: * the <i>display name</i> is the same as the virtual machine
106: * identifier.
107: *
108: * @param provider The AttachProvider to attach to the Java virtual machine.
109: * @param id The virtual machine identifier.
110: *
111: * @throws NullPointerException
112: * If <tt>provider</tt> or <tt>id</tt> is <tt>null</tt>.
113: */
114: public VirtualMachineDescriptor(AttachProvider provider, String id) {
115: this (provider, id, id);
116: }
117:
118: /**
119: * Return the <code>AttachProvider</code> that this descriptor references.
120: *
121: * @return The <code>AttachProvider</code> that this descriptor references.
122: */
123: public AttachProvider provider() {
124: return provider;
125: }
126:
127: /**
128: * Return the identifier component of this descriptor.
129: *
130: * @return The identifier component of this descriptor.
131: */
132: public String id() {
133: return id;
134: }
135:
136: /**
137: * Return the <i>display name</i> component of this descriptor.
138: *
139: * @return The display name component of this descriptor.
140: */
141: public String displayName() {
142: return displayName;
143: }
144:
145: /**
146: * Returns a hash-code value for this VirtualMachineDescriptor. The hash
147: * code is based upon the descriptor's components, and satifies
148: * the general contract of the {@link java.lang.Object#hashCode()
149: * Object.hashCode} method.
150: *
151: * @return A hash-code value for this descriptor.
152: */
153: public int hashCode() {
154: if (hash != 0) {
155: return hash;
156: }
157: hash = provider.hashCode() * 127 + id.hashCode();
158: return hash;
159: }
160:
161: /**
162: * Tests this VirtualMachineDescriptor for equality with another object.
163: *
164: * <p> If the given object is not a VirtualMachineDescriptor then this
165: * method returns <tt>false</tt>. For two VirtualMachineDescriptors to
166: * be considered equal requires that they both reference the same
167: * provider, and their {@link #id() identifiers} are equal. </p>
168: *
169: * <p> This method satisfies the general contract of the {@link
170: * java.lang.Object#equals(Object) Object.equals} method. </p>
171: *
172: * @param ob The object to which this object is to be compared
173: *
174: * @return <tt>true</tt> if, and only if, the given object is
175: * a VirtualMachineDescriptor that is equal to this
176: * VirtualMachineDescriptor.
177: */
178: public boolean equals(Object ob) {
179: if (ob == this )
180: return true;
181: if (!(ob instanceof VirtualMachineDescriptor))
182: return false;
183: VirtualMachineDescriptor other = (VirtualMachineDescriptor) ob;
184: if (other.provider() != this .provider()) {
185: return false;
186: }
187: if (!other.id().equals(this .id())) {
188: return false;
189: }
190: return true;
191: }
192:
193: /**
194: * Returns the string representation of the <code>VirtualMachineDescriptor</code>.
195: */
196: public String toString() {
197: String s = provider.toString() + ": " + id;
198: if (displayName != id) {
199: s += " " + displayName;
200: }
201: return s;
202: }
203:
204: }
|