< prev index next >

src/jdk.jvmstat/share/classes/sun/jvmstat/monitor/VmIdentifier.java

Print this page




  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package sun.jvmstat.monitor;
  27 
  28 import java.net.*;
  29 
  30 /**
  31  * An abstraction that identifies a target Java Virtual Machine.
  32  * The VmIdentifier, or vmid, provides a convenient string representation
  33  * of the information needed to locate and communicate with a target
  34  * Java Virtual Machine. The string, based on a {@link URI}, may specify
  35  * the communications protocol, host name, local vm identifier, and protocol
  36  * specific information for a target Java Virtual Machine. The format for
  37  * a VmIdentifier string is:
  38  * <pre>
  39  *      [<I>protocol</I>:][<I>//</I>]<I><B>lvmid</B></I>[<I>@hostname</I>][<I>:port</I>][<I>/servername</I>]
  40  * </pre>
  41  * The only required component of this string is the Local Virtual Machine
  42  * Identifier, or <tt>lvmid</tt>, which uniquely identifies the target
  43  * Java Virtual Machine on a host. The optional components of the VmIdentifier
  44  * include:
  45  * <ul>
  46  *   <li><p><tt>protocol</tt> - The communications protocol. A VmIdentifier
  47  *          omitting the protocol must be resolved against a HostIdentifier
  48  *          using {@link HostIdentifier#resolve}.
  49  *       </p></li>
  50  *   <li><p><tt>hostname</tt> - A hostname or IP address indicating the target
  51  *          host. A VmIdentifier omitting the protocol must be resolved
  52  *          against a HostIdentifier using {@link HostIdentifier#resolve}.
  53  *       </p></li>
  54  *   <li><p><tt>port</tt> - The port for the communications protocol.
  55  *          Treatment of the <tt>port</tt> parameter is implementation
  56  *          (protocol) specific. A VmIdentifier omitting the protocol should
  57  *          be resolved against a HostIdentifier using
  58  *          {@link HostIdentifier#resolve}.
  59  *       </p></li>
  60  *   <li><p><tt>servername</tt> - The treatment of the Path, Query, and
  61  *          Fragment components of the VmIdentifier are implementation
  62  *          (protocol) dependent. A VmIdentifier omitting the protocol should
  63  *          be resolved against a HostIdentifier using
  64  *          {@link HostIdentifier#resolve}.
  65  *       </p></li>
  66  * </ul>
  67  * <p>
  68  * All VmIdentifier instances are constructed as absolute, hierarchical URIs.
  69  * The constructors will accept relative (and even some malformed,
  70  * though convenient) URI strings. Such strings are transformed into
  71  * legitimate, absolute URI strings.
  72  * </p>
  73  * <p>
  74  * With the exception of <em>file:</em> based VmIdentifier strings, all
  75  * VmIdentifier strings must include a <tt>lvmid</tt>. Attempting to construct
  76  * a non-file based VmIdentifier that doesn't include a <tt>lvmid</tt>
  77  * component will result in a <tt>MonitorException</tt>.
  78  * </p>
  79  * <p>
  80  * Here are some examples of VmIdentifier strings.
  81  * <ul>
  82  *    <li><p>Relative URIs</p></li>
  83  *      <ul>
  84  *         <li><p><em>1234</em> - Specifies the Java Virtual Machine
  85  *                identified by lvmid <em>1234</em> on an unnamed host.
  86  *                This string is transformed into the absolute form
  87  *                <em>//1234</em>, which must be resolved against a
  88  *                HostIdentifier.
  89  *         </p></li>
  90  *         <li><p><em>1234@hostname</em> - Specifies the Java Virtual
  91  *                Machine identified by lvmid <em>1234</em> on host
  92  *                <em>hostname</em> with an unnamed protocol.
  93  *                This string is transformed into the absolute form
  94  *                <em>//1234@hostname</em>, which must be resolved against
  95  *                a HostIdentifier.
  96  *         </p></li>
  97  *         <li><p><em>1234@hostname:2099</em> - Specifies the Java Virtual
  98  *                Machine identified by lvmid <em>1234</em> on host
  99  *                <em>hostname</em> with an unnamed protocol, but with
 100  *                port <em>2099</em>. This string is transformed into
 101  *                the absolute form <em>//1234@hostname:2099</em>, which
 102  *                must be resolved against a HostIdentifier.
 103  *         </p></li>
 104  *      </ul>
 105  *    <li><p>Absolute URIs</p></li>

 106  *      <ul>
 107  *         <li><p><em>rmi://1234@hostname:2099/remoteobjectname</em> -
 108  *                Specifies the Java Virtual Machine identified by lvmid
 109  *                <em>1234</em> on host <em>hostname</em> accessed
 110  *                using the <em>rmi:</em> protocol through the rmi remote
 111  *                object named <em>remoteobjectname</em> as registered with
 112  *                the <em>rmiserver</em> on port <em>2099</em> on host
 113  *                <em>hostname</em>.
 114  *         </p></li>
 115  *         <li><p><em>file:/path/file</em> - Identifies a Java Virtual Machine
 116  *                through accessing a special file based protocol to use as
 117  *                the communications mechanism.
 118  *         </p></li>
 119  *      </ul>

 120  * </ul>
 121  * </p>
 122  *
 123  * @see URI
 124  * @see HostIdentifier
 125  * @author Brian Doherty
 126  * @since 1.5
 127  */
 128 public class VmIdentifier {
 129     private URI uri;
 130 
 131     /**
 132      * creates a canonical representation of the uriString. This method
 133      * performs certain translations depending on the type of URI generated
 134      * by the string.
 135      */
 136     private URI canonicalize(String uriString) throws URISyntaxException {
 137         if (uriString == null) {
 138             uriString = "local://0@localhost";
 139             return new URI(uriString);
 140         }
 141 


 219      * @param uri a well formed, absolute URI indicating the
 220      *            target Java Virtual Machine.
 221      * @throws URISyntaxException Thrown if the URI is missing some
 222      *                            required component.
 223      */
 224     public VmIdentifier(URI uri) throws URISyntaxException {
 225         this.uri = uri;
 226         validate();
 227     }
 228 
 229     /**
 230      * Return the corresponding HostIdentifier for this VmIdentifier.
 231      * <p>
 232      * This method constructs a HostIdentifier object from the VmIdentifier.
 233      * If the VmIdentifier is not specific about the protocol or other
 234      * components of the URI, then the resulting HostIdentifier will
 235      * be constructed based on this missing information. Typically, the
 236      * missing components will have result in the HostIdentifier assigning
 237      * assumed defaults that allow the VmIdentifier to be resolved according
 238      * to those defaults.
 239      * </p>
 240      * <p>
 241      * For example, a VmIdentifier that specifies only a <tt>lvmid</tt>
 242      * will result in a HostIdentifier for <em>localhost</em> utilizing
 243      * the default local protocol, <em>local:</em>. A VmIdentifier that
 244      * specifies both a <tt>vmid</tt> and a <tt>hostname</tt> will result
 245      * in a HostIdentifier for the specified host with the default remote
 246      * protocol, <em>rmi:</em>, using the protocol defaults for the
 247      * <tt>port</tt> and <tt>servername</tt> components.
 248      * </p>
 249      *
 250      * @return HostIdentifier - the host identifier for the host containing
 251      *                          the Java Virtual Machine represented by this
 252      *                          VmIdentifier.
 253      * @throws URISyntaxException Thrown if a bad host URI is constructed.
 254      *                            This exception may get encapsulated into
 255      *                            a MonitorException in a future version.
 256      */
 257     public HostIdentifier getHostIdentifier() throws URISyntaxException {
 258         StringBuilder sb = new StringBuilder();
 259         if (getScheme() != null) {
 260             sb.append(getScheme()).append(":");
 261         }
 262         sb.append("//").append(getHost());
 263         if (getPort() != -1) {
 264             sb.append(":").append(getPort());
 265         }
 266         if (getPath() != null) {
 267             sb.append(getPath());
 268         }




  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package sun.jvmstat.monitor;
  27 
  28 import java.net.*;
  29 
  30 /**
  31  * An abstraction that identifies a target Java Virtual Machine.
  32  * The VmIdentifier, or vmid, provides a convenient string representation
  33  * of the information needed to locate and communicate with a target
  34  * Java Virtual Machine. The string, based on a {@link URI}, may specify
  35  * the communications protocol, host name, local vm identifier, and protocol
  36  * specific information for a target Java Virtual Machine. The format for
  37  * a VmIdentifier string is:
  38  * <pre>
  39  *      [<I>protocol</I>:][<I>//</I>]<I><B>lvmid</B></I>[<I>@hostname</I>][<I>:port</I>][<I>/servername</I>]
  40  * </pre>
  41  * The only required component of this string is the Local Virtual Machine
  42  * Identifier, or {@code lvmid}, which uniquely identifies the target
  43  * Java Virtual Machine on a host. The optional components of the VmIdentifier
  44  * include:
  45  * <ul>
  46  *   <li>{@code protocol} - The communications protocol. A VmIdentifier
  47  *       omitting the protocol must be resolved against a HostIdentifier
  48  *       using {@link HostIdentifier#resolve}.
  49  *       </li>
  50  *   <li>{@code hostname} - A hostname or IP address indicating the target
  51  *       host. A VmIdentifier omitting the protocol must be resolved
  52  *       against a HostIdentifier using {@link HostIdentifier#resolve}.
  53  *       </li>
  54  *   <li>{@code port} - The port for the communications protocol.
  55  *       Treatment of the {@code port} parameter is implementation
  56  *       (protocol) specific. A VmIdentifier omitting the protocol should
  57  *       be resolved against a HostIdentifier using
  58  *       {@link HostIdentifier#resolve}.
  59  *       </li>
  60  *   <li>{@code servername} - The treatment of the Path, Query, and
  61  *       Fragment components of the VmIdentifier are implementation
  62  *       (protocol) dependent. A VmIdentifier omitting the protocol should
  63  *       be resolved against a HostIdentifier using
  64  *       {@link HostIdentifier#resolve}.
  65  *       </li>
  66  * </ul>
  67  * <p>
  68  * All VmIdentifier instances are constructed as absolute, hierarchical URIs.
  69  * The constructors will accept relative (and even some malformed,
  70  * though convenient) URI strings. Such strings are transformed into
  71  * legitimate, absolute URI strings.

  72  * <p>
  73  * With the exception of <em>file:</em> based VmIdentifier strings, all
  74  * VmIdentifier strings must include a {@code lvmid}. Attempting to construct
  75  * a non-file based VmIdentifier that doesn't include a {@code lvmid}
  76  * component will result in a {@code MonitorException}.

  77  * <p>
  78  * Here are some examples of VmIdentifier strings.
  79  * <ul>
  80  *    <li>Relative URIs
  81  *      <ul>
  82  *         <li><em>1234</em> - Specifies the Java Virtual Machine
  83  *             identified by lvmid <em>1234</em> on an unnamed host.
  84  *             This string is transformed into the absolute form
  85  *             <em>//1234</em>, which must be resolved against a
  86  *             HostIdentifier.
  87  *         </li>
  88  *         <li><em>1234@hostname</em> - Specifies the Java Virtual
  89  *             Machine identified by lvmid <em>1234</em> on host
  90  *             <em>hostname</em> with an unnamed protocol.
  91  *             This string is transformed into the absolute form
  92  *             <em>//1234@hostname</em>, which must be resolved against
  93  *             a HostIdentifier.
  94  *         </li>
  95  *         <li><em>1234@hostname:2099</em> - Specifies the Java Virtual
  96  *             Machine identified by lvmid <em>1234</em> on host
  97  *             <em>hostname</em> with an unnamed protocol, but with
  98  *             port <em>2099</em>. This string is transformed into
  99  *             the absolute form <em>//1234@hostname:2099</em>, which
 100  *             must be resolved against a HostIdentifier.
 101  *         </li>
 102  *      </ul>
 103  *    </li>
 104  *    <li>Absolute URIs
 105  *      <ul>
 106  *         <li><em>rmi://1234@hostname:2099/remoteobjectname</em> -
 107  *             Specifies the Java Virtual Machine identified by lvmid
 108  *             <em>1234</em> on host <em>hostname</em> accessed
 109  *             using the <em>rmi:</em> protocol through the rmi remote
 110  *             object named <em>remoteobjectname</em> as registered with
 111  *             the <em>rmiserver</em> on port <em>2099</em> on host
 112  *             <em>hostname</em>.
 113  *         </li>
 114  *         <li><em>file:/path/file</em> - Identifies a Java Virtual Machine
 115  *             through accessing a special file based protocol to use as
 116  *             the communications mechanism.
 117  *         </li>
 118  *      </ul>
 119  *    </li>
 120  * </ul>

 121  *
 122  * @see URI
 123  * @see HostIdentifier
 124  * @author Brian Doherty
 125  * @since 1.5
 126  */
 127 public class VmIdentifier {
 128     private URI uri;
 129 
 130     /**
 131      * creates a canonical representation of the uriString. This method
 132      * performs certain translations depending on the type of URI generated
 133      * by the string.
 134      */
 135     private URI canonicalize(String uriString) throws URISyntaxException {
 136         if (uriString == null) {
 137             uriString = "local://0@localhost";
 138             return new URI(uriString);
 139         }
 140 


 218      * @param uri a well formed, absolute URI indicating the
 219      *            target Java Virtual Machine.
 220      * @throws URISyntaxException Thrown if the URI is missing some
 221      *                            required component.
 222      */
 223     public VmIdentifier(URI uri) throws URISyntaxException {
 224         this.uri = uri;
 225         validate();
 226     }
 227 
 228     /**
 229      * Return the corresponding HostIdentifier for this VmIdentifier.
 230      * <p>
 231      * This method constructs a HostIdentifier object from the VmIdentifier.
 232      * If the VmIdentifier is not specific about the protocol or other
 233      * components of the URI, then the resulting HostIdentifier will
 234      * be constructed based on this missing information. Typically, the
 235      * missing components will have result in the HostIdentifier assigning
 236      * assumed defaults that allow the VmIdentifier to be resolved according
 237      * to those defaults.

 238      * <p>
 239      * For example, a VmIdentifier that specifies only a {@code lvmid}
 240      * will result in a HostIdentifier for <em>localhost</em> utilizing
 241      * the default local protocol, <em>local:</em>. A VmIdentifier that
 242      * specifies both a {@code vmid} and a {@code hostname} will result
 243      * in a HostIdentifier for the specified host with the default remote
 244      * protocol, <em>rmi:</em>, using the protocol defaults for the
 245      * {@code port} and {@code servername} components.

 246      *
 247      * @return HostIdentifier - the host identifier for the host containing
 248      *                          the Java Virtual Machine represented by this
 249      *                          VmIdentifier.
 250      * @throws URISyntaxException Thrown if a bad host URI is constructed.
 251      *                            This exception may get encapsulated into
 252      *                            a MonitorException in a future version.
 253      */
 254     public HostIdentifier getHostIdentifier() throws URISyntaxException {
 255         StringBuilder sb = new StringBuilder();
 256         if (getScheme() != null) {
 257             sb.append(getScheme()).append(":");
 258         }
 259         sb.append("//").append(getHost());
 260         if (getPort() != -1) {
 261             sb.append(":").append(getPort());
 262         }
 263         if (getPath() != null) {
 264             sb.append(getPath());
 265         }


< prev index next >