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

/*
 * Copyright 2004 Sun Microsystems, Inc.  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.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */

package sun.jvmstat.monitor;

import java.net.*;

/**
 * An abstraction that identifies a target host and communications
 * protocol. The HostIdentifier, or hostid, provides a convenient string
 * representation of the information needed to locate and communicate with
 * a target host. The string, based on a {@link URI}, may specify the
 * the communications protocol, host name, and protocol specific information
 * for a target host. The format for a HostIdentifier string is:
 * <pre>
 *       [<I>protocol</I>:][[<I>//</I>]<I>hostname</I>][<I>:port</I>][<I>/servername</I>]
 * </pre>
 * There are actually no required components of this string, as a null string
 * is interpreted to mean a local connection to the local host and is equivalent
 * to the string <em>local://localhost</em>. The components of the
 * HostIdentifier are:
 * <ul>
 *   <li><p><tt>protocol</tt> - The communications protocol. If omitted,
 *          and a hostname is not specified, then default local protocol,
 *          <em>local:</em>, is assumed. If the protocol is omitted and a
 *          hostname is specified then the default remote protocol,
 *          <em>rmi:</em> is assumed.
 *       </p></li>
 *   <li><p><tt>hostname</tt> - The hostname. If omitted, then
 *          <em>localhost</em> is assumed. If the protocol is also omitted,
 *          then default local protocol <em>local:</em> is also assumed.
 *          If the hostname is not omitted but the protocol is omitted,
 *          then the default remote protocol, <em>rmi:</em> is assumed.
 *       </p></li>
 *   <li><p><tt>port</tt> - The port for the communications protocol.
 *          Treatment of the <tt>port</tt> parameter is implementation
 *          (protocol) specific. It is unused by the default local protocol,
 *          <em>local:</em>. For the default remote protocol, <em>rmi:</em>,
 *          <tt>port</tt> indicates the port number of the <em>rmiregistry</em>
 *          on the target host and defaults to port 1099.
 *       </p></li>
 *   <li><p><tt>servername</tt> - The treatment of the Path, Query, and
 *          Fragment components of the HostIdentifier are implementation
 *          (protocol) dependent. These components are ignored by the
 *          default local protocol, <em>local:</em>. For the default remote
 *          protocol, <em>rmi</em>, the Path component is interpreted as
 *          the name of the RMI remote object. The Query component may
 *          contain an access mode specifier <em>?mode=</em> specifying
 *          <em>"r"</em> or <em>"rw"</em> access (write access currently
 *          ignored). The Fragment part is ignored.
 *       </p></li>
 * </ul>
 * <p>
 * All HostIdentifier objects are represented as absolute, hierarchical URIs.
 * The constructors accept relative URIs, but these will generally be
 * transformed into an absolute URI specifying a default protocol. A
 * HostIdentifier differs from a URI in that certain contractions and
 * illicit syntactical constructions are allowed. The following are all
 * valid HostIdentifier strings:
 *
 * <ul>
 *   <li><p>&lt null &gt - transformed into "//localhost"</p></li>
 *   <li><p>localhost - transformed into "//localhost"</p></li>
 *   <li><p>hostname - transformed into "//hostname"</p></li>
 *   <li><p>hostname:port - transformed into "//hostname:port"</p></li>
 *   <li><p>proto:hostname - transformed into "proto://hostname"</p></li>
 *   <li><p>proto:hostname:port - transformed into
 *          "proto://hostname:port"</p></li>
 *   <li><p>proto://hostname:port</p></li>
 * </ul>
 * </p>
 *
 * @see URI
 * @see VmIdentifier
 *
 * @author Brian Doherty
 * @since 1.5
 */
public class HostIdentifier {
    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.compareTo("localhost") == 0)) {
            uriString = "//localhost";
            return new URI(uriString);
        }

        URI u = new URI(uriString);

        if (u.isAbsolute()) {
            if (u.isOpaque()) {
                /*
                 * this code is here to deal with a special case. For ease of
                 * use, we'd like to be able to handle the case where the user
                 * specifies hostname:port, not requiring the scheme part.
                 * This introduces some subtleties.
                 *     hostname:port - scheme = hostname
                 *                   - schemespecificpart = port
                 *                   - hostname = null
                 *                   - userinfo=null
                 * however, someone could also enter scheme:hostname:port and
                 * get into this code. the strategy is to consider this
                 * syntax illegal and provide some code to defend against it.
                 * Basically, we test that the string contains only one ":"
                 * and that the ssp is numeric. If we get two colons, we will
                 * attempt to insert the "//" after the first colon and then
                 * try to create a URI from the resulting string.
                 */
                String scheme = u.getScheme();
                String ssp = u.getSchemeSpecificPart();
                String frag = u.getFragment();
                URI u2 = null;

                int c1index = uriString.indexOf(":");
                int c2index = uriString.lastIndexOf(":");
                if (c2index != c1index) {
                    /*
                     * this is the scheme:hostname:port case. Attempt to
                     * transform this to scheme://hostname:port. If a path
                     * part is part of the original strings, it will be
                     * included in the SchemeSpecificPart. however, the
                     * fragment part must be handled separately.
                     */
                    if (frag == null) {
                        u2 = new URI(scheme + "://" + ssp);
                    } else {
                        u2 = new URI(scheme + "://" + ssp + "#" + frag);
                    }
                    return u2;
                }
                /*
                 * here we have the <string>:<string> case, possibly with
                 * optional path and fragment components. we assume that
                 * the part following the colon is a number. we don't check
                 * this condition here as it will get detected later anyway.
                 */
                u2 = new URI("//" + uriString);
                return u2;
            } else {
                return u;
            }
        } else {
            /*
             * This is the case where we were given a hostname followed
             * by a path part, fragment part, or both a path and fragment
             * part. The key here is that no scheme part was specified.
             * For this case, if the scheme specific part does not begin
             * with "//", then we prefix the "//" to the given string and
             * attempt to create a URI from the resulting string.
             */
            String ssp = u.getSchemeSpecificPart();
            if (ssp.startsWith("//")) {
                return u;
            } else {
                return new URI("//" + uriString);
            }
        }
    }

    /**
     * Create a HostIdentifier instance from a string value.
     *
     * @param uriString a string representing a target host. The syntax of
     *                  the string must conform to the rules specified in the
     *                  class documentation.
     *
     * @throws URISyntaxException Thrown when the uriString or its canonical
     *                            form is poorly formed. This exception may
     *                            get encapsulated into a MonitorException in
     *                            a future version.
     *
     */
    public HostIdentifier(String uriString) throws URISyntaxException {
        uri = canonicalize(uriString);
    }

    /**
     * Create a HostIdentifier instance from component parts of a URI.
     *
     * @param scheme the {@link URI#getScheme} component of a URI.
     * @param authority the {@link URI#getAuthority} component of a URI.
     * @param path the {@link URI#getPath} component of a URI.
     * @param query the {@link URI#getQuery} component of a URI.
     * @param fragment the {@link URI#getFragment} component of a URI.
     *
     * @throws URISyntaxException Thrown when the uriString or its canonical
     *                            form is poorly formed. This exception may
     *                            get encapsulated into a MonitorException in
     *                            a future version.
     * @see URI
     */
    public HostIdentifier(String scheme, String authority, String path,
                          String query, String fragment)
           throws URISyntaxException {
        uri = new URI(scheme, authority, path, query, fragment);
    }

    /**
     * Create a HostIdentifier instance from a VmIdentifier.
     *
     * The necessary components of the VmIdentifier are extracted and
     * reassembled into a HostIdentifier. If a "file:" scheme (protocol)
     * is specified, the the returned HostIdentifier will always be
     * equivalent to HostIdentifier("file://localhost").
     *
     * @param vmid the VmIdentifier use to construct the HostIdentifier.
     */
    public HostIdentifier(VmIdentifier vmid) {
        /*
         * Extract all components of the VmIdentifier URI except the
         * user-info part of the authority (the lvmid).
         */
        StringBuilder sb = new StringBuilder();
        String scheme = vmid.getScheme();
        String host = vmid.getHost();
        String authority = vmid.getAuthority();

        // check for 'file:' VmIdentifiers and handled as a special case.
        if ((scheme != null) && (scheme.compareTo("file") == 0)) {
            try {
                uri = new URI("file://localhost");
            } catch (URISyntaxException e) { };
            return;
        }

        if ((host != null) && (host.compareTo(authority) == 0)) {
            /*
             * this condition occurs when the VmIdentifier specifies only
             * the authority (i.e. the lvmid ), and not a host name.
             */
            host = null;
        }

        if (scheme == null) {
            if (host == null) {
                scheme = "local";            // default local scheme
            } else {
                /*
                 * rmi is the default remote scheme. if the VmIdentifier
                 * specifies some other protocol, this default is overridden.
                 */
                scheme = "rmi";
            }
        }

        sb.append(scheme).append("://");

        if (host == null) {
            sb.append("localhost");          // default host name
        } else {
            sb.append(host);
        }

        int port = vmid.getPort();
        if (port != -1) {
            sb.append(":").append(port);
        }

        String path = vmid.getPath();
        if ((path != null) && (path.length() != 0)) {
            sb.append(path);
        }

        String query = vmid.getQuery();
        if (query != null) {
            sb.append("?").append(query);
        }

        String frag = vmid.getFragment();
        if (frag != null) {
            sb.append("#").append(frag);
        }

        try {
           uri = new URI(sb.toString());
        } catch (URISyntaxException e) {
           // shouldn't happen, as we were passed a valid VmIdentifier
           throw new RuntimeException("Internal Error", e);
        }
    }

    /**
     * Resolve a VmIdentifier with this HostIdentifier. A VmIdentifier, such
     * as <em>1234</em> or <em>1234@hostname</em> or any other string that
     * omits certain components of the URI string may be valid, but is certainly
     * incomplete. They are missing critical information for identifying the
     * the communications protocol, target host, or other parameters. A
     * VmIdentifier of this form is considered <em>unresolved</em>. This method
     * uses components of the HostIdentifier to resolve the missing components
     * of the VmIdentifier.
     * <p>
     * Specified components of the unresolved VmIdentifier take precedence
     * over their HostIdentifier counterparts. For example, if the VmIdentifier
     * indicates <em>1234@hostname:2099</em> and the HostIdentifier indicates
     * <em>rmi://hostname:1099/</em>, then the resolved VmIdentifier will
     * be <em>rmi://1234@hostname:2099</em>. Any component not explicitly
     * specified or assumed by the HostIdentifier, will remain unresolved in
     * resolved VmIdentifier.
     *  <p>
     * A VmIdentifier specifying a <em>file:</em> scheme (protocol), is
     * not changed in any way by this method.
     *
     * @param vmid the unresolved VmIdentifier.
     * @return VmIdentifier - the resolved VmIdentifier. If vmid was resolved
     *                        on entry to this method, then the returned
     *                        VmIdentifier will be equal, but not identical, to
     *                        vmid.
     */
    public VmIdentifier resolve(VmIdentifier vmid)
           throws URISyntaxException, MonitorException {
        String scheme = vmid.getScheme();
        String host = vmid.getHost();
        String authority = vmid.getAuthority();

        if ((scheme != null) && (scheme.compareTo("file") == 0)) {
            // don't attempt to resolve a file based VmIdentifier.
            return vmid;
        }

        if ((host != null) && (host.compareTo(authority) == 0)) {
            /*
             * this condition occurs when the VmIdentifier specifies only
             * the authority (i.e. an lvmid), and not a host name.
             */
            host = null;
        }

        if (scheme == null) {
            scheme = getScheme();
        }

        URI nuri = null;

        StringBuffer sb = new StringBuffer();

        sb.append(scheme).append("://");

        String userInfo = vmid.getUserInfo();
        if (userInfo != null) {
            sb.append(userInfo);
        } else {
            sb.append(vmid.getAuthority());
        }

        if (host == null) {
            host = getHost();
        }
        sb.append("@").append(host);

        int port = vmid.getPort();
        if (port == -1) {
            port = getPort();
        }

        if (port != -1) {
            sb.append(":").append(port);
        }

        String path = vmid.getPath();
        if ((path == null) || (path.length() == 0)) {
            path = getPath();
        }

        if ((path != null) && (path.length() > 0)) {
            sb.append(path);
        }

        String query = vmid.getQuery();
        if (query == null) {
            query = getQuery();
        }
        if (query != null) {
            sb.append("?").append(query);
        }

        String fragment = vmid.getFragment();
        if (fragment == null) {
            fragment = getFragment();
        }
        if (fragment != null) {
            sb.append("#").append(fragment);
        }

        String s = sb.toString();
        return new VmIdentifier(s);
    }

    /**
     * Return the Scheme, or protocol, portion of this HostIdentifier.
     *
     * @return String - the scheme for this HostIdentifier.
     * @see URI#getScheme()
     */
    public String getScheme() {
        return uri.isAbsolute() ? uri.getScheme() : null;
    }

    /**
     * Return the Scheme Specific Part of this HostIdentifier.
     *
     * @return String - the scheme specific part for this HostIdentifier.
     * @see URI#getSchemeSpecificPart()
     */
    public String getSchemeSpecificPart() {
        return  uri.getSchemeSpecificPart();
    }

    /**
     * Return the User Info part of this HostIdentifier.
     *
     * @return String - the user info part for this HostIdentifier.
     * @see URI#getUserInfo()
     */
    public String getUserInfo() {
        return uri.getUserInfo();
    }

    /**
     * Return the Host part of this HostIdentifier.
     *
     * @return String - the host part for this HostIdentifier, or
     *                  "localhost" if the URI.getHost() returns null.
     * @see URI#getUserInfo()
     */
    public String getHost() {
        return (uri.getHost() == null) ? "localhost" : uri.getHost();
    }

    /**
     * Return the Port for of this HostIdentifier.
     *
     * @return String - the port for this HostIdentifier
     * @see URI#getPort()
     */
    public int getPort() {
        return uri.getPort();
    }

    /**
     * Return the Path part of this HostIdentifier.
     *
     * @return String - the path part for this HostIdentifier.
     * @see URI#getPath()
     */
    public String getPath() {
        return uri.getPath();
    }

    /**
     * Return the Query part of this HostIdentifier.
     *
     * @return String - the query part for this HostIdentifier.
     * @see URI#getQuery()
     */
    public String getQuery() {
        return uri.getQuery();
    }

    /**
     * Return the Fragment part of this HostIdentifier.
     *
     * @return String - the fragment part for this HostIdentifier.
     * @see URI#getFragment()
     */
    public String getFragment() {
        return uri.getFragment();
    }

    /**
     * Return the mode indicated in this HostIdentifier.
     *
     * @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 HostIdentifier.
     *
     * @return URI - the URI.
     * @see URI
     */
    public URI getURI() {
        return uri;
    }

    /**
     * Return the hash code for this HostIdentifier. 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
     *                   HostIdentifier and its URI field is equal to this
     *                   object's URI field. Otherwise, returns false.
     *
     * @see URI#equals(Object)
     */
    public boolean equals(Object object) {
        if (object == this) {
            return true;
        }
        if (!(object instanceof HostIdentifier)) {
            return false;
        }
        return uri.equals(((HostIdentifier)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 HostIdentifier.
     *
     * @see URI#toString()
     */
    public String toString() {
        return uri.toString();
    }
}