sun.jvmstat.monitor

Class VmIdentifier

java.lang.Object

sun.jvmstat.monitor.VmIdentifier

public class VmIdentifier
extends Object

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 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:

      [protocol:][//]lvmid[@hostname][:port][/servername]
 

The only required component of this string is the Local Virtual Machine Identifier, or lvmid, which uniquely identifies the target Java Virtual Machine on a host. The optional components of the VmIdentifier include:

• protocol - The communications protocol. A VmIdentifier omitting the protocol must be resolved against a HostIdentifier using HostIdentifier.resolve(sun.jvmstat.monitor.VmIdentifier).

• hostname - A hostname or IP address indicating the target host. A VmIdentifier omitting the protocol must be resolved against a HostIdentifier using HostIdentifier.resolve(sun.jvmstat.monitor.VmIdentifier).

• port - The port for the communications protocol. Treatment of the port parameter is implementation (protocol) specific. A VmIdentifier omitting the protocol should be resolved against a HostIdentifier using HostIdentifier.resolve(sun.jvmstat.monitor.VmIdentifier).

• servername - 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 HostIdentifier.resolve(sun.jvmstat.monitor.VmIdentifier).

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.

With the exception of file: based VmIdentifier strings, all VmIdentifier strings must include a lvmid. Attempting to construct a non-file based VmIdentifier that doesn't include a lvmid component will result in a MonitorException.

Here are some examples of VmIdentifier strings.

• Relative URIs

• 1234 - Specifies the Java Virtual Machine identified by lvmid 1234 on an unnamed host. This string is transformed into the absolute form //1234, which must be resolved against a HostIdentifier.

• 1234@hostname - Specifies the Java Virtual Machine identified by lvmid 1234 on host hostname with an unnamed protocol. This string is transformed into the absolute form //1234@hostname, which must be resolved against a HostIdentifier.

• 1234@hostname:2099 - Specifies the Java Virtual Machine identified by lvmid 1234 on host hostname with an unnamed protocol, but with port 2099. This string is transformed into the absolute form //1234@hostname:2099, which must be resolved against a HostIdentifier.

• Absolute URIs

• rmi://1234@hostname:2099/remoteobjectname - Specifies the Java Virtual Machine identified by lvmid 1234 on host hostname accessed using the rmi: protocol through the rmi remote object named remoteobjectname as registered with the rmiserver on port 2099 on host hostname.

• file:/path/file - Identifies a Java Virtual Machine through accessing a special file based protocol to use as the communications mechanism.

Since:

1.5

Author:

Brian Doherty

See Also:

URI, HostIdentifier

Constructor Summary

Constructors

Constructor and Description
VmIdentifier(String uriString) Create a VmIdentifier instance from a string value.
VmIdentifier(URI uri) Create a VmIdentifier instance from a URI object.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object object) Test for quality with other objects.
String	getAuthority() Return the Authority part of this VmIdentifier.
String	getFragment() Return the Fragment part of this VmIdentifier.
String	getHost() Return the Host part of this VmIdentifier.
HostIdentifier	getHostIdentifier() Return the corresponding HostIdentifier for this VmIdentifier.
int	getLocalVmId() Return the Local Virtual Machine Identifier for this VmIdentifier.
String	getMode() Return the mode indicated in this VmIdentifier.
String	getPath() Return the Path part of this VmIdentifier.
int	getPort() Return the Port part of this VmIdentifier.
String	getQuery() Return the Query part of this VmIdentifier.
String	getScheme() Return the Scheme, or protocol, portion of this VmIdentifier.
String	getSchemeSpecificPart() Return the Scheme Specific Part of this VmIdentifier.
URI	getURI() Return the URI associated with the VmIdentifier.
String	getUserInfo() Return the UserInfo part of this VmIdentifier.
int	hashCode() Return the hash code for this VmIdentifier.
String	toString() Convert to a string representation.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

VmIdentifier

public VmIdentifier(String uriString)
             throws URISyntaxException

Create a VmIdentifier instance from a string value.

Parameters:

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.

VmIdentifier

public VmIdentifier(URI uri)
             throws URISyntaxException

Create a VmIdentifier instance from a URI object.

Parameters:

uri - a well formed, absolute URI indicating the target Java Virtual Machine.

Throws:

URISyntaxException - Thrown if the URI is missing some required component.

Method Detail

getHostIdentifier

public HostIdentifier getHostIdentifier()
                                 throws URISyntaxException

Return the corresponding HostIdentifier for this VmIdentifier.

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.

For example, a VmIdentifier that specifies only a lvmid will result in a HostIdentifier for localhost utilizing the default local protocol, local:. A VmIdentifier that specifies both a vmid and a hostname will result in a HostIdentifier for the specified host with the default remote protocol, rmi:, using the protocol defaults for the port and servername components.

Returns:

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.

getScheme

public String getScheme()

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

Returns:

String - the scheme for this VmIdentifier.

See Also:

URI.getScheme()

getSchemeSpecificPart

public String getSchemeSpecificPart()

Return the Scheme Specific Part of this VmIdentifier.

Returns:

String - the Scheme Specific Part for this VmIdentifier.

See Also:

URI.getSchemeSpecificPart()

getUserInfo

public String getUserInfo()

Return the UserInfo part of this VmIdentifier.

Returns:

String - the UserInfo part for this VmIdentifier.

See Also:

URI.getUserInfo()

getHost

public String getHost()

Return the Host part of this VmIdentifier.

Returns:

String - the Host part for this VmIdentifier.

See Also:

URI.getHost()

getPort

public int getPort()

Return the Port part of this VmIdentifier.

Returns:

int - the Port part for this VmIdentifier.

See Also:

URI.getPort()

getAuthority

public String getAuthority()

Return the Authority part of this VmIdentifier.

Returns:

String - the Authority part for this VmIdentifier.

See Also:

URI.getAuthority()

getPath

public String getPath()

Return the Path part of this VmIdentifier.

Returns:

String - the Path part for this VmIdentifier.

See Also:

URI.getPath()

getQuery

public String getQuery()

Return the Query part of this VmIdentifier.

Returns:

String - the Query part for this VmIdentifier.

See Also:

URI.getQuery()

getFragment

public String getFragment()

Return the Fragment part of this VmIdentifier.

Returns:

String - the Fragment part for this VmIdentifier.

See Also:

URI.getFragment()

getLocalVmId

public int getLocalVmId()

Return the Local Virtual Machine Identifier for this VmIdentifier. The Local Virtual Machine Identifier is also known as the lvmid.

Returns:

int - the lvmid for this VmIdentifier.

getMode

public String getMode()

Return the mode indicated in this VmIdentifier.

Returns:

String - the mode string. If no mode is specified, then "r" is returned. otherwise, the specified mode is returned.

getURI

public URI getURI()

Return the URI associated with the VmIdentifier.

Returns:

URI - the URI.

See Also:

URI

hashCode

public int hashCode()

Return the hash code for this VmIdentifier. The hash code is identical to the hash code for the contained URI.

Overrides:

hashCode in class Object

Returns:

int - the hashcode.

See Also:

URI.hashCode()

equals

public boolean equals(Object object)

Test for quality with other objects.

Overrides:

equals in class Object

Parameters:

object - the object to be test for equality.

Returns:

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 Also:

URI.equals(Object)

toString

public String toString()

Convert to a string representation. Conversion is identical to calling getURI().toString(). This may change in a future release.

Overrides:

toString in class Object

Returns:

String - a String representation of the VmIdentifier.

See Also:

URI.toString()