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 public class VirtualMachineDescriptor {
  59 
  60     private AttachProvider provider;
  61     private String id;
  62     private String displayName;
  63 
  64     private volatile int hash;        // 0 => not computed
  65 
  66     /**
  67      * Creates a virtual machine descriptor from the given components.
  68      *
  69      * @param   provider      The AttachProvider to attach to the Java virtual machine.
  70      * @param   id            The virtual machine identifier.
  71      * @param   displayName   The display name.
  72      *
  73      * @throws  NullPointerException
  74      *          If any of the arguments are <code>null</code>
  75      */
  76     public VirtualMachineDescriptor(AttachProvider provider, String id, String displayName) {
  77         if (provider == null) {
  78             throw new NullPointerException("provider cannot be null");
  79         }
  80         if (id == null) {
  81             throw new NullPointerException("identifier cannot be null");
  82         }
  83         if (displayName == null) {
  84             throw new NullPointerException("display name cannot be null");
  85         }
  86         this.provider = provider;
  87         this.id = id;
  88         this.displayName = displayName;
  89     }
  90 
  91     /**
  92      * Creates a virtual machine descriptor from the given components.
  93      *
  94      * <p> This convenience constructor works as if by invoking the
  95      * three-argument constructor as follows:
  96      *
  97      * <blockquote><tt>
  98      * new&nbsp;{@link #VirtualMachineDescriptor(AttachProvider, String, String)
  99      * VirtualMachineDescriptor}(provider, &nbsp;id, &nbsp;id);
 100      * </tt></blockquote>
 101      *
 102      * <p> That is, it creates a virtual machine descriptor such that
 103      * the <i>display name</i> is the same as the virtual machine
 104      * identifier.
 105      *
 106      * @param   provider      The AttachProvider to attach to the Java virtual machine.
 107      * @param   id            The virtual machine identifier.
 108      *
 109      * @throws  NullPointerException
 110      *          If <tt>provider</tt> or <tt>id</tt> is <tt>null</tt>.
 111      */
 112     public VirtualMachineDescriptor(AttachProvider provider, String id) {
 113         this(provider, id, id);
 114     }
 115 
 116     /**
 117      * Return the <code>AttachProvider</code> that this descriptor references.
 118      *
 119      * @return The <code>AttachProvider</code> that this descriptor references.
 120      */
 121     public AttachProvider provider() {
 122         return provider;
 123     }
 124 
 125     /**
 126      * Return the identifier component of this descriptor.
 127      *
 128      * @return  The identifier component of this descriptor.
 129      */
 130     public String id() {
 131         return id;
 132     }
 133 
 134     /**
 135      * Return the <i>display name</i> component of this descriptor.
 136      *
 137      * @return  The display name component of this descriptor.
 138      */
 139     public String displayName() {
 140         return displayName;
 141     }
 142 
 143     /**
 144      * Returns a hash-code value for this VirtualMachineDescriptor. The hash
 145      * code is based upon the descriptor's components, and satifies
 146      * the general contract of the {@link java.lang.Object#hashCode()
 147      * Object.hashCode} method.
 148      *
 149      * @return  A hash-code value for this descriptor.
 150      */
 151     public int hashCode() {
 152         if (hash != 0) {
 153             return hash;
 154         }
 155         hash = provider.hashCode() * 127 + id.hashCode();
 156         return hash;
 157     }
 158 
 159     /**
 160      * Tests this VirtualMachineDescriptor for equality with another object.
 161      *
 162      * <p> If the given object is not a VirtualMachineDescriptor then this
 163      * method returns <tt>false</tt>. For two VirtualMachineDescriptors to
 164      * be considered equal requires that they both reference the same
 165      * provider, and their {@link #id() identifiers} are equal. </p>
 166      *
 167      * <p> This method satisfies the general contract of the {@link
 168      * java.lang.Object#equals(Object) Object.equals} method. </p>
 169      *
 170      * @param   ob   The object to which this object is to be compared
 171      *
 172      * @return  <tt>true</tt> if, and only if, the given object is
 173      *                a VirtualMachineDescriptor that is equal to this
 174      *                VirtualMachineDescriptor.
 175      */
 176     public boolean equals(Object ob) {
 177         if (ob == this)
 178             return true;
 179         if (!(ob instanceof VirtualMachineDescriptor))
 180             return false;
 181         VirtualMachineDescriptor other = (VirtualMachineDescriptor)ob;
 182         if (other.provider() != this.provider()) {
 183             return false;
 184         }
 185         if (!other.id().equals(this.id())) {
 186             return false;
 187         }
 188         return true;
 189     }
 190 
 191     /**
 192      * Returns the string representation of the <code>VirtualMachineDescriptor</code>.
 193      */
 194     public String toString() {
 195         String s = provider.toString() + ": " + id;
 196         if (displayName != id) {
 197             s += " " + displayName;
 198         }
 199         return s;
 200     }
 201 
 202 
 203 }