A VirtualMachineDescriptor is a container class used to
* describe a Java virtual machine. It encapsulates an identifier that identifies
* a target virtual machine, and a reference to the {@link
* com.sun.tools.attach.spi.AttachProvider AttachProvider} that should be used
* when attempting to attach to the virtual machine. The identifier is
* implementation-dependent but is typically the process identifier (or pid)
* environments where each Java virtual machine runs in its own operating system
* process.
A VirtualMachineDescriptor also has a {@link #displayName() displayName}.
* The display name is typically a human readable string that a tool might
* display to a user. For example, a tool that shows a list of Java
* virtual machines running on a system might use the display name rather
* than the identifier. A VirtualMachineDescriptor may be
* created without a display name. In that case the identifier is
* used as the display name.
*
*
VirtualMachineDescriptor instances are typically created by
* invoking the {@link com.sun.tools.attach.VirtualMachine#list VirtualMachine.list()}
* method. This returns the complete list of descriptors to describe the
* Java virtual machines known to all installed {@link
* com.sun.tools.attach.spi.AttachProvider attach providers}.
*
* @since 1.6
*/
@jdk.Supported
public class VirtualMachineDescriptor {
private AttachProvider provider;
private String id;
private String displayName;
private volatile int hash; // 0 => not computed
/**
* Creates a virtual machine descriptor from the given components.
*
* @param provider The AttachProvider to attach to the Java virtual machine.
* @param id The virtual machine identifier.
* @param displayName The display name.
*
* @throws NullPointerException
* If any of the arguments are null
*/
public VirtualMachineDescriptor(AttachProvider provider, String id, String displayName) {
if (provider == null) {
throw new NullPointerException("provider cannot be null");
}
if (id == null) {
throw new NullPointerException("identifier cannot be null");
}
if (displayName == null) {
throw new NullPointerException("display name cannot be null");
}
this.provider = provider;
this.id = id;
this.displayName = displayName;
}
/**
* Creates a virtual machine descriptor from the given components.
*
*
This convenience constructor works as if by invoking the * three-argument constructor as follows: * *
* new {@link #VirtualMachineDescriptor(AttachProvider, String, String) * VirtualMachineDescriptor}(provider, id, id); ** *
That is, it creates a virtual machine descriptor such that
* the display name is the same as the virtual machine
* identifier.
*
* @param provider The AttachProvider to attach to the Java virtual machine.
* @param id The virtual machine identifier.
*
* @throws NullPointerException
* If provider or id is null.
*/
public VirtualMachineDescriptor(AttachProvider provider, String id) {
this(provider, id, id);
}
/**
* Return the AttachProvider that this descriptor references.
*
* @return The AttachProvider that this descriptor references.
*/
public AttachProvider provider() {
return provider;
}
/**
* Return the identifier component of this descriptor.
*
* @return The identifier component of this descriptor.
*/
public String id() {
return id;
}
/**
* Return the display name component of this descriptor.
*
* @return The display name component of this descriptor.
*/
public String displayName() {
return displayName;
}
/**
* Returns a hash-code value for this VirtualMachineDescriptor. The hash
* code is based upon the descriptor's components, and satifies
* the general contract of the {@link java.lang.Object#hashCode()
* Object.hashCode} method.
*
* @return A hash-code value for this descriptor.
*/
public int hashCode() {
if (hash != 0) {
return hash;
}
hash = provider.hashCode() * 127 + id.hashCode();
return hash;
}
/**
* Tests this VirtualMachineDescriptor for equality with another object.
*
*
If the given object is not a VirtualMachineDescriptor then this * method returns false. For two VirtualMachineDescriptors to * be considered equal requires that they both reference the same * provider, and their {@link #id() identifiers} are equal.
* *This method satisfies the general contract of the {@link * java.lang.Object#equals(Object) Object.equals} method.
* * @param ob The object to which this object is to be compared * * @return true if, and only if, the given object is * a VirtualMachineDescriptor that is equal to this * VirtualMachineDescriptor. */ public boolean equals(Object ob) { if (ob == this) return true; if (!(ob instanceof VirtualMachineDescriptor)) return false; VirtualMachineDescriptor other = (VirtualMachineDescriptor)ob; if (other.provider() != this.provider()) { return false; } if (!other.id().equals(this.id())) { return false; } return true; } /** * Returns the string representation of theVirtualMachineDescriptor.
*/
public String toString() {
String s = provider.toString() + ": " + id;
if (displayName != id) {
s += " " + displayName;
}
return s;
}
}