/* * Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package sun.jvmstat.monitor; import java.net.*; /** * An abstraction that identifies a target Java Virtual Machine. * The VmIdentifier, or vmid, provides a convenient string representation * of the information needed to locate and communicate with a target * Java Virtual Machine. The string, based on a {@link URI}, may specify * the communications protocol, host name, local vm identifier, and protocol * specific information for a target Java Virtual Machine. The format for * a VmIdentifier string is: * <pre> *      [<I>protocol</I>:][<I>//</I>]<I><B>lvmid</B></I>[<I>@hostname</I>][<I>:port</I>][<I>/servername</I>] * </pre> * The only required component of this string is the Local Virtual Machine * Identifier, or <tt>lvmid</tt>, which uniquely identifies the target * Java Virtual Machine on a host. The optional components of the VmIdentifier * include: * <ul> *   <li><p><tt>protocol</tt> - The communications protocol. A VmIdentifier *          omitting the protocol must be resolved against a HostIdentifier *          using {@link HostIdentifier#resolve}. *       </p></li> *   <li><p><tt>hostname</tt> - A hostname or IP address indicating the target *          host. A VmIdentifier omitting the protocol must be resolved *          against a HostIdentifier using {@link HostIdentifier#resolve}. *       </p></li> *   <li><p><tt>port</tt> - The port for the communications protocol. *          Treatment of the <tt>port</tt> parameter is implementation *          (protocol) specific. A VmIdentifier omitting the protocol should *          be resolved against a HostIdentifier using *          {@link HostIdentifier#resolve}. *       </p></li> *   <li><p><tt>servername</tt> - The treatment of the Path, Query, and *          Fragment components of the VmIdentifier are implementation *          (protocol) dependent. A VmIdentifier omitting the protocol should *          be resolved against a HostIdentifier using *          {@link HostIdentifier#resolve}. *       </p></li> * </ul> * <p> * All VmIdentifier instances are constructed as absolute, hierarchical URIs. * The constructors will accept relative (and even some malformed, * though convenient) URI strings. Such strings are transformed into * legitimate, absolute URI strings. * </p> * <p> * With the exception of <em>file:</em> based VmIdentifier strings, all * VmIdentifier strings must include a <tt>lvmid</tt>. Attempting to construct * a non-file based VmIdentifier that doesn't include a <tt>lvmid</tt> * component will result in a <tt>MonitorException</tt>. * </p> * <p> * Here are some examples of VmIdentifier strings. * <ul> *    <li><p>Relative URIs</p></li> *      <ul> *         <li><p><em>1234</em> - Specifies the Java Virtual Machine *                identified by lvmid <em>1234</em> on an unnamed host. *                This string is transformed into the absolute form *                <em>//1234</em>, which must be resolved against a *                HostIdentifier. *         </p></li> *         <li><p><em>1234@hostname</em> - Specifies the Java Virtual *                Machine identified by lvmid <em>1234</em> on host *                <em>hostname</em> with an unnamed protocol. *                This string is transformed into the absolute form *                <em>//1234@hostname</em>, which must be resolved against *                a HostIdentifier. *         </p></li> *         <li><p><em>1234@hostname:2099</em> - Specifies the Java Virtual *                Machine identified by lvmid <em>1234</em> on host *                <em>hostname</em> with an unnamed protocol, but with *                port <em>2099</em>. This string is transformed into *                the absolute form <em>//1234@hostname:2099</em>, which *                must be resolved against a HostIdentifier. *         </p></li> *      </ul> *    <li><p>Absolute URIs</p></li> *      <ul> *         <li><p><em>rmi://1234@hostname:2099/remoteobjectname</em> - *                Specifies the Java Virtual Machine identified by lvmid *                <em>1234</em> on host <em>hostname</em> accessed *                using the <em>rmi:</em> protocol through the rmi remote *                object named <em>remoteobjectname</em> as registered with *                the <em>rmiserver</em> on port <em>2099</em> on host *                <em>hostname</em>. *         </p></li> *         <li><p><em>file:/path/file</em> - Identifies a Java Virtual Machine *                through accessing a special file based protocol to use as *                the communications mechanism. *         </p></li> *      </ul> * </ul> * </p> * * @see URI * @see HostIdentifier * @author Brian Doherty * @since 1.5 */public class VmIdentifier {    private URI uri;     /**     * creates a canonical representation of the uriString. This method     * performs certain translations depending on the type of URI generated     * by the string.     */    private URI canonicalize(String uriString) throws URISyntaxException {        if (uriString == null) {            uriString = "local://0@localhost";            return new URI(uriString);        }         URI u = new URI(uriString);         if (u.isAbsolute()) {            if (u.isOpaque()) {                /*                 * rmi:1234@hostname/path#fragment converted to                 * rmi://1234@hostname/path#fragment                 */                u = new URI(u.getScheme(), "//" + u.getSchemeSpecificPart(),                            u.getFragment());            }        } else {            /*             * make the uri absolute, if possible. A relative URI doesn't             * specify the scheme part, so it's safe to prepend a "//" and             * try again.             */            if (!uriString.startsWith("//")) {                if (u.getFragment() == null) {                    u = new URI("//" + u.getSchemeSpecificPart());                } else {                    u = new URI("//" + u.getSchemeSpecificPart() + "#"                                + u.getFragment());                }            }        }        return u;    }     /**     * check that the VmIdentifier includes a unique numerical identifier     * for the target JVM.     */    private void validate() throws URISyntaxException {        // file:// uri, which is a special case where the lvmid is not required.        String s = getScheme();        if ((s != null) && (s.compareTo("file") == 0)) {            return;        }        if (getLocalVmId() == -1) {            throw new URISyntaxException(uri.toString(), "Local vmid required");        }    }     /**     * Create a VmIdentifier instance from a string value.     *     * @param uriString a string representing a target Java Virtual Machine.     *                  The syntax of the string must conforms to the rules     *                  specified in the class documentation.     * @throws URISyntaxException Thrown when the uriString or its canonical     *                            form is poorly formed.     */    public VmIdentifier(String uriString) throws URISyntaxException {        URI u;        try {            u = canonicalize(uriString);        } catch (URISyntaxException e) {            /*             * a vmid of the form 1234@hostname:1098 causes an exception,             * so try again with a leading "//"             */            if (uriString.startsWith("//")) {                throw e;            }            u = canonicalize("//"+uriString);        }         uri = u;         // verify that we have a valid lvmid        validate();    }     /**     * Create a VmIdentifier instance from a URI object.     *     * @param uri a well formed, absolute URI indicating the     *            target Java Virtual Machine.     * @throws URISyntaxException Thrown if the URI is missing some     *                            required component.     */    public VmIdentifier(URI uri) throws URISyntaxException {        this.uri = uri;        validate();    }     /**     * Return the corresponding HostIdentifier for this VmIdentifier.     * <p>     * This method constructs a HostIdentifier object from the VmIdentifier.     * If the VmIdentifier is not specific about the protocol or other     * components of the URI, then the resulting HostIdentifier will     * be constructed based on this missing information. Typically, the     * missing components will have result in the HostIdentifier assigning     * assumed defaults that allow the VmIdentifier to be resolved according     * to those defaults.     * </p>     * <p>     * For example, a VmIdentifier that specifies only a <tt>lvmid</tt>     * will result in a HostIdentifier for <em>localhost</em> utilizing     * the default local protocol, <em>local:</em>. A VmIdentifier that     * specifies both a <tt>vmid</tt> and a <tt>hostname</tt> will result     * in a HostIdentifier for the specified host with the default remote     * protocol, <em>rmi:</em>, using the protocol defaults for the     * <tt>port</tt> and <tt>servername</tt> components.     * </p>     *     * @return HostIdentifier - the host identifier for the host containing     *                          the Java Virtual Machine represented by this     *                          VmIdentifier.     * @throws URISyntaxException Thrown if a bad host URI is constructed.     *                            This exception may get encapsulated into     *                            a MonitorException in a future version.     */    public HostIdentifier getHostIdentifier() throws URISyntaxException {        StringBuffer sb = new StringBuffer();        if (getScheme() != null) {            sb.append(getScheme()).append(":");        }        sb.append("//").append(getHost());        if (getPort() != -1) {            sb.append(":").append(getPort());        }        if (getPath() != null) {            sb.append(getPath());        }        return new HostIdentifier(sb.toString());    }     /**     * Return the Scheme, or protocol, portion of this VmIdentifier.     *     * @return String - the scheme for this VmIdentifier.     * @see URI#getScheme()     */    public String getScheme() {        return uri.getScheme();    }     /**     * Return the Scheme Specific Part of this VmIdentifier.     *     * @return String - the Scheme Specific Part for this VmIdentifier.     * @see URI#getSchemeSpecificPart()     */    public String getSchemeSpecificPart() {        return uri.getSchemeSpecificPart();    }     /**     * Return the UserInfo part of this VmIdentifier.     *     * @return String - the UserInfo part for this VmIdentifier.     * @see URI#getUserInfo()     */    public String getUserInfo() {        return uri.getUserInfo();    }     /**     * Return the Host part of this VmIdentifier.     *     * @return String - the Host part for this VmIdentifier.     * @see URI#getHost()     */    public String getHost() {        return uri.getHost();    }     /**     * Return the Port part of this VmIdentifier.     *     * @return int - the Port part for this VmIdentifier.     * @see URI#getPort()     */    public int getPort() {        return uri.getPort();    }     /**     * Return the Authority part of this VmIdentifier.     *     * @return String - the Authority part for this VmIdentifier.     * @see URI#getAuthority()     */    public String getAuthority() {        return uri.getAuthority();    }     /**     * Return the Path part of this VmIdentifier.     *     * @return String - the Path part for this VmIdentifier.     * @see URI#getPath()     */    public String getPath() {        return uri.getPath();    }     /**     * Return the Query part of this VmIdentifier.     *     * @return String - the Query part for this VmIdentifier.     * @see URI#getQuery()     */    public String getQuery() {        return uri.getQuery();    }     /**     * Return the Fragment part of this VmIdentifier.     *     * @return String - the Fragment part for this VmIdentifier.     * @see URI#getFragment()     */    public String getFragment() {        return uri.getFragment();    }     /**     * Return the Local Virtual Machine Identifier for this VmIdentifier.     * The Local Virtual Machine Identifier is also known as the     * <em>lvmid</em>.     *     * @return int - the lvmid for this VmIdentifier.     */    public int getLocalVmId() {        int result = -1;        try {            if (uri.getUserInfo() == null) {                result = Integer.parseInt(uri.getAuthority());            } else {                result = Integer.parseInt(uri.getUserInfo());            }        } catch (NumberFormatException e) { }        return result;    }     /**     * Return the mode indicated in this VmIdentifier.     *     * @return String - the mode string. If no mode is specified, then "r"     *                  is returned. otherwise, the specified mode is returned.     */    public String getMode() {        String query = getQuery();        if (query != null) {            String[] queryArgs = query.split("\\+");            for (int i = 0; i < queryArgs.length; i++) {                if (queryArgs[i].startsWith("mode=")) {                    int index = queryArgs[i].indexOf('=');                    return queryArgs[i].substring(index+1);                }            }        }        return "r";    }     /**     * Return the URI associated with the VmIdentifier.     *     * @return URI - the URI.     * @see URI     */    public URI getURI() {        return uri;    }     /**     * Return the hash code for this VmIdentifier. The hash code is     * identical to the hash code for the contained URI.     *     * @return int - the hashcode.     * @see URI#hashCode()     */    public int hashCode() {        return uri.hashCode();    }     /**     * Test for quality with other objects.     *     * @param object the object to be test for equality.     * @return boolean - returns true if the given object is of type     *                   VmIdentifier and its URI field is equal to     *                   this object's URI field. Otherwise, return false.     *     * @see URI#equals(Object)     */    public boolean equals(Object object) {        if (object == this) {            return true;        }        if (!(object instanceof VmIdentifier)) {            return false;        }        return uri.equals(((VmIdentifier)object).uri);    }     /**     * Convert to a string representation. Conversion is identical to     * calling getURI().toString(). This may change in a future release.     *     * @return String - a String representation of the VmIdentifier.     *     * @see URI#toString()     */    public String toString() {        return uri.toString();    }}