1 /*

     2  * Copyright (c) 2004, 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 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 

   141         URI u = new URI(uriString);

   142 

   143         if (u.isAbsolute()) {

   144             if (u.isOpaque()) {

   145                 /*

   146                  * rmi:1234@hostname/path#fragment converted to

   147                  * rmi://1234@hostname/path#fragment

   148                  */

   149                 u = new URI(u.getScheme(), "//" + u.getSchemeSpecificPart(),

   150                             u.getFragment());

   151             }

   152         } else {

   153             /*

   154              * make the uri absolute, if possible. A relative URI doesn't

   155              * specify the scheme part, so it's safe to prepend a "//" and

   156              * try again.

   157              */

   158             if (!uriString.startsWith("//")) {

   159                 if (u.getFragment() == null) {

   160                     u = new URI("//" + u.getSchemeSpecificPart());

   161                 } else {

   162                     u = new URI("//" + u.getSchemeSpecificPart() + "#"

   163                                 + u.getFragment());

   164                 }

   165             }

   166         }

   167         return u;

   168     }

   169 

   170     /**

   171      * check that the VmIdentifier includes a unique numerical identifier

   172      * for the target JVM.

   173      */

   174     private void validate() throws URISyntaxException {

   175         // file:// uri, which is a special case where the lvmid is not required.

   176         String s = getScheme();

   177         if ((s != null) && (s.compareTo("file") == 0)) {

   178             return;

   179         }

   180         if (getLocalVmId() == -1) {

   181             throw new URISyntaxException(uri.toString(), "Local vmid required");

   182         }

   183     }

   184 

   185     /**

   186      * Create a VmIdentifier instance from a string value.

   187      *

   188      * @param uriString a string representing a target Java Virtual Machine.

   189      *                  The syntax of the string must conforms to the rules

   190      *                  specified in the class documentation.

   191      * @throws URISyntaxException Thrown when the uriString or its canonical

   192      *                            form is poorly formed.

   193      */

   194     public VmIdentifier(String uriString) throws URISyntaxException {

   195         URI u;

   196         try {

   197             u = canonicalize(uriString);

   198         } catch (URISyntaxException e) {

   199             /*

   200              * a vmid of the form 1234@hostname:1098 causes an exception,

   201              * so try again with a leading "//"

   202              */

   203             if (uriString.startsWith("//")) {

   204                 throw e;

   205             }

   206             u = canonicalize("//"+uriString);

   207         }

   208 

   209         uri = u;

   210 

   211         // verify that we have a valid lvmid

   212         validate();

   213     }

   214 

   215     /**

   216      * Create a VmIdentifier instance from a URI object.

   217      *

   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         }

   266         return new HostIdentifier(sb.toString());

   267     }

   268 

   269     /**

   270      * Return the Scheme, or protocol, portion of this VmIdentifier.

   271      *

   272      * @return String - the scheme for this VmIdentifier.

   273      * @see URI#getScheme()

   274      */

   275     public String getScheme() {

   276         return uri.getScheme();

   277     }

   278 

   279     /**

   280      * Return the Scheme Specific Part of this VmIdentifier.

   281      *

   282      * @return String - the Scheme Specific Part for this VmIdentifier.

   283      * @see URI#getSchemeSpecificPart()

   284      */

   285     public String getSchemeSpecificPart() {

   286         return uri.getSchemeSpecificPart();

   287     }

   288 

   289     /**

   290      * Return the UserInfo part of this VmIdentifier.

   291      *

   292      * @return String - the UserInfo part for this VmIdentifier.

   293      * @see URI#getUserInfo()

   294      */

   295     public String getUserInfo() {

   296         return uri.getUserInfo();

   297     }

   298 

   299     /**

   300      * Return the Host part of this VmIdentifier.

   301      *

   302      * @return String - the Host part for this VmIdentifier.

   303      * @see URI#getHost()

   304      */

   305     public String getHost() {

   306         return uri.getHost();

   307     }

   308 

   309     /**

   310      * Return the Port part of this VmIdentifier.

   311      *

   312      * @return int - the Port part for this VmIdentifier.

   313      * @see URI#getPort()

   314      */

   315     public int getPort() {

   316         return uri.getPort();

   317     }

   318 

   319     /**

   320      * Return the Authority part of this VmIdentifier.

   321      *

   322      * @return String - the Authority part for this VmIdentifier.

   323      * @see URI#getAuthority()

   324      */

   325     public String getAuthority() {

   326         return uri.getAuthority();

   327     }

   328 

   329     /**

   330      * Return the Path part of this VmIdentifier.

   331      *

   332      * @return String - the Path part for this VmIdentifier.

   333      * @see URI#getPath()

   334      */

   335     public String getPath() {

   336         return uri.getPath();

   337     }

   338 

   339     /**

   340      * Return the Query part of this VmIdentifier.

   341      *

   342      * @return String - the Query part for this VmIdentifier.

   343      * @see URI#getQuery()

   344      */

   345     public String getQuery() {

   346         return uri.getQuery();

   347     }

   348 

   349     /**

   350      * Return the Fragment part of this VmIdentifier.

   351      *

   352      * @return String - the Fragment part for this VmIdentifier.

   353      * @see URI#getFragment()

   354      */

   355     public String getFragment() {

   356         return uri.getFragment();

   357     }

   358 

   359     /**

   360      * Return the Local Virtual Machine Identifier for this VmIdentifier.

   361      * The Local Virtual Machine Identifier is also known as the

   362      * <em>lvmid</em>.

   363      *

   364      * @return int - the lvmid for this VmIdentifier.

   365      */

   366     public int getLocalVmId() {

   367         int result = -1;

   368         try {

   369             if (uri.getUserInfo() == null) {

   370                 result = Integer.parseInt(uri.getAuthority());

   371             } else {

   372                 result = Integer.parseInt(uri.getUserInfo());

   373             }

   374         } catch (NumberFormatException e) { }

   375         return result;

   376     }

   377 

   378     /**

   379      * Return the mode indicated in this VmIdentifier.

   380      *

   381      * @return String - the mode string. If no mode is specified, then "r"

   382      *                  is returned. otherwise, the specified mode is returned.

   383      */

   384     public String getMode() {

   385         String query = getQuery();

   386         if (query != null) {

   387             String[] queryArgs = query.split("\\+");

   388             for (int i = 0; i < queryArgs.length; i++) {

   389                 if (queryArgs[i].startsWith("mode=")) {

   390                     int index = queryArgs[i].indexOf('=');

   391                     return queryArgs[i].substring(index+1);

   392                 }

   393             }

   394         }

   395         return "r";

   396     }

   397 

   398     /**

   399      * Return the URI associated with the VmIdentifier.

   400      *

   401      * @return URI - the URI.

   402      * @see URI

   403      */

   404     public URI getURI() {

   405         return uri;

   406     }

   407 

   408     /**

   409      * Return the hash code for this VmIdentifier. The hash code is

   410      * identical to the hash code for the contained URI.

   411      *

   412      * @return int - the hashcode.

   413      * @see URI#hashCode()

   414      */

   415     public int hashCode() {

   416         return uri.hashCode();

   417     }

   418 

   419     /**

   420      * Test for quality with other objects.

   421      *

   422      * @param object the object to be test for equality.

   423      * @return boolean - returns true if the given object is of type

   424      *                   VmIdentifier and its URI field is equal to

   425      *                   this object's URI field. Otherwise, return false.

   426      *

   427      * @see URI#equals(Object)

   428      */

   429     public boolean equals(Object object) {

   430         if (object == this) {

   431             return true;

   432         }

   433         if (!(object instanceof VmIdentifier)) {

   434             return false;

   435         }

   436         return uri.equals(((VmIdentifier)object).uri);

   437     }

   438 

   439     /**

   440      * Convert to a string representation. Conversion is identical to

   441      * calling getURI().toString(). This may change in a future release.

   442      *

   443      * @return String - a String representation of the VmIdentifier.

   444      *

   445      * @see URI#toString()

   446      */

   447     public String toString() {

   448         return uri.toString();

   449     }

   450 }