sun.jvmstat.monitor

Class HostIdentifier

java.lang.Object

sun.jvmstat.monitor.HostIdentifier

public class HostIdentifier
extends Object

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 URI, may specify the the communications protocol, host name, and protocol specific information for a target host. The format for a HostIdentifier string is:

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

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 local://localhost. The components of the HostIdentifier are:

• protocol - The communications protocol. If omitted, and a hostname is not specified, then default local protocol, local:, is assumed. If the protocol is omitted and a hostname is specified then the default remote protocol, rmi: is assumed.

• hostname - The hostname. If omitted, then localhost is assumed. If the protocol is also omitted, then default local protocol local: is also assumed. If the hostname is not omitted but the protocol is omitted, then the default remote protocol, rmi: is assumed.

• port - The port for the communications protocol. Treatment of the port parameter is implementation (protocol) specific. It is unused by the default local protocol, local:. For the default remote protocol, rmi:, port indicates the port number of the rmiregistry on the target host and defaults to port 1099.

• servername - 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, local:. For the default remote protocol, rmi, the Path component is interpreted as the name of the RMI remote object. The Query component may contain an access mode specifier ?mode= specifying "r" or "rw" access (write access currently ignored). The Fragment part is ignored.

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:

• < null > - transformed into "//localhost"

• localhost - transformed into "//localhost"

• hostname - transformed into "//hostname"

• hostname:port - transformed into "//hostname:port"

• proto:hostname - transformed into "proto://hostname"

• proto:hostname:port - transformed into "proto://hostname:port"

• proto://hostname:port

Since:

1.5

Author:

Brian Doherty

See Also:

URI, VmIdentifier

Constructor Summary

Constructors

Constructor and Description
HostIdentifier(String uriString) Create a HostIdentifier instance from a string value.
HostIdentifier(String scheme, String authority, String path, String query, String fragment) Create a HostIdentifier instance from component parts of a URI.
HostIdentifier(VmIdentifier vmid) Create a HostIdentifier instance from a VmIdentifier.

Method Summary

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

Methods inherited from class java.lang.Object

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

Constructor Detail

HostIdentifier

public HostIdentifier(String uriString)
               throws URISyntaxException

Create a HostIdentifier instance from a string value.

Parameters:

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.

HostIdentifier

public HostIdentifier(String scheme,
                      String authority,
                      String path,
                      String query,
                      String fragment)
               throws URISyntaxException

Create a HostIdentifier instance from component parts of a URI.

Parameters:

scheme - the URI.getScheme() component of a URI.

authority - the URI.getAuthority() component of a URI.

path - the URI.getPath() component of a URI.

query - the URI.getQuery() component of a URI.

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

URI

HostIdentifier

public HostIdentifier(VmIdentifier vmid)

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").

Parameters:

vmid - the VmIdentifier use to construct the HostIdentifier.

Method Detail

resolve

public VmIdentifier resolve(VmIdentifier vmid)
                     throws URISyntaxException,
                            MonitorException

Resolve a VmIdentifier with this HostIdentifier. A VmIdentifier, such as 1234 or 1234@hostname 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 unresolved. This method uses components of the HostIdentifier to resolve the missing components of the VmIdentifier.

Specified components of the unresolved VmIdentifier take precedence over their HostIdentifier counterparts. For example, if the VmIdentifier indicates 1234@hostname:2099 and the HostIdentifier indicates rmi://hostname:1099/, then the resolved VmIdentifier will be rmi://1234@hostname:2099. Any component not explicitly specified or assumed by the HostIdentifier, will remain unresolved in resolved VmIdentifier.

A VmIdentifier specifying a file: scheme (protocol), is not changed in any way by this method.

Parameters:

vmid - the unresolved VmIdentifier.

Returns:

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.

Throws:

URISyntaxException

MonitorException

getScheme

public String getScheme()

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

Returns:

String - the scheme for this HostIdentifier.

See Also:

URI.getScheme()

getSchemeSpecificPart

public String getSchemeSpecificPart()

Return the Scheme Specific Part of this HostIdentifier.

Returns:

String - the scheme specific part for this HostIdentifier.

See Also:

URI.getSchemeSpecificPart()

getUserInfo

public String getUserInfo()

Return the User Info part of this HostIdentifier.

Returns:

String - the user info part for this HostIdentifier.

See Also:

URI.getUserInfo()

getHost

public String getHost()

Return the Host part of this HostIdentifier.

Returns:

String - the host part for this HostIdentifier, or "localhost" if the URI.getHost() returns null.

See Also:

URI.getUserInfo()

getPort

public int getPort()

Return the Port for of this HostIdentifier.

Returns:

String - the port for this HostIdentifier

See Also:

URI.getPort()

getPath

public String getPath()

Return the Path part of this HostIdentifier.

Returns:

String - the path part for this HostIdentifier.

See Also:

URI.getPath()

getQuery

public String getQuery()

Return the Query part of this HostIdentifier.

Returns:

String - the query part for this HostIdentifier.

See Also:

URI.getQuery()

getFragment

public String getFragment()

Return the Fragment part of this HostIdentifier.

Returns:

String - the fragment part for this HostIdentifier.

See Also:

URI.getFragment()

getMode

public String getMode()

Return the mode indicated in this HostIdentifier.

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 HostIdentifier.

Returns:

URI - the URI.

See Also:

URI

hashCode

public int hashCode()

Return the hash code for this HostIdentifier. 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 HostIdentifier and its URI field is equal to this object's URI field. Otherwise, returns 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 HostIdentifier.

See Also:

URI.toString()