Back to index...

	/*
	* 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();
	}
	}

Back to index...