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.util.*;
	import java.net.*;
	import java.lang.reflect.*;

	import sun.jvmstat.monitor.event.HostListener;

	/**
	* An abstraction for a host that contains instrumented Java Virtual
	* Machines. The class provides abstract factory methods for creating
	* concrete instances of this class and factory methods for creating
	* {@link MonitoredVm} instances. Concrete implementations of this class
	* provide methods for managing the communications protocols and provide
	* for event notification.
	*
	* @author Brian Doherty
	* @since 1.5
	*
	* @see HostIdentifier
	* @see VmIdentifier
	* @see MonitoredVm
	* @see HostListener
	*/
	public abstract class MonitoredHost {
	private static Map<HostIdentifier, MonitoredHost> monitoredHosts =
	new HashMap<HostIdentifier, MonitoredHost>();

	/*
	* The monitoring implementation override mechanism. The value of
	* this property is used as the class name for the concrete MonitoredHost
	* subclass that implements the monitoring APIs. Setting this property
	* will cause the remaining override mechanisms to be ignored. When
	* this mechanism is used, the HostIdentifier scheme name, which
	* indicates the communications protocol, is not used to locate a
	* the protocol specific package. However, the HostIdentifier is
	* still passed to the corresponding single arg constructor.
	* This property is not expected to be set in normal circumstances.
	*/
	private static final String IMPL_OVERRIDE_PROP_NAME =
	"sun.jvmstat.monitor.MonitoredHost";

	/*
	* The monitoring package name override mechanism. The value
	* the this property is used as base package name for the
	* monitoring implementation package. This property is not
	* expected to be set under normal circumstances.
	*/
	private static final String IMPL_PKG_PROP_NAME =
	"sun.jvmstat.monitor.package";
	private static final String IMPL_PACKAGE =
	System.getProperty(IMPL_PKG_PROP_NAME, "sun.jvmstat.perfdata");

	/*
	* The default optimized local protocol override mechanism. The value
	* of this property is used to construct the default package name
	* for the default optimized local protocol as follows:
	* <IMPL_PACKAGE>.monitor.<LOCAL_PROTOCOL>
	* This property is not expected to be set under normal circumstances.
	*/
	private static final String LOCAL_PROTOCOL_PROP_NAME =
	"sun.jvmstat.monitor.local";
	private static final String LOCAL_PROTOCOL =
	System.getProperty(LOCAL_PROTOCOL_PROP_NAME, "local");

	/*
	* The default remote protocol override mechanism. The value of
	* this property is used to construct the default package name
	* for the default remote protocol protocol as follows:
	* <IMPL_PACKAGE>.monitor.protocol.<REMOTE_PROTOCOL>
	* This property is not expected to be set under normal circumstances.
	*/
	private static final String REMOTE_PROTOCOL_PROP_NAME =
	"sun.jvmstat.monitor.remote";
	private static final String REMOTE_PROTOCOL =
	System.getProperty(REMOTE_PROTOCOL_PROP_NAME, "rmi");

	/*
	* The default class name of the MonitoredHost implementation subclass.
	* There is no override mechanism for this variable, other than the
	* IMPL_OVERRIDE_PROP_NAME override, which is larger in scope. A concrete
	* instance of this class is expected to be found in:
	* <IMPL_PACKAGE>.monitor.protocol.<protocol>.<MONITORED_HOST_CLASS>
	*/
	private static final String MONITORED_HOST_CLASS = "MonitoredHostProvider";

	/**
	* The HostIdentifier for this MonitoredHost instance.
	*/
	protected HostIdentifier hostId;

	/**
	* The polling interval, in milliseconds, for this MonitoredHost instance.
	*/
	protected int interval;

	/**
	* The last Exception encountered while polling this MonitoredHost.
	*/
	protected Exception lastException;

	/**
	* Factory method to construct MonitoredHost instances to manage
	* connections to the host indicated by <tt>hostIdString</tt>
	*
	* @param hostIdString a String representation of a {@link HostIdentifier}
	* @return MonitoredHost - the MonitoredHost instance for communicating
	* with the indicated host using the protocol
	* specified in hostIdString.
	* @throws MonitorException Thrown if monitoring errors occur.
	* @throws URISyntaxException Thrown when the hostIdString is poorly
	* formed. This exception may get encapsulated
	* into MonitorException in a future revision.
	*/
	public static MonitoredHost getMonitoredHost(String hostIdString)
	throws MonitorException, URISyntaxException {
	HostIdentifier hostId = new HostIdentifier(hostIdString);
	return getMonitoredHost(hostId);
	}

	/**
	* Factory method to construct a MonitoredHost instance to manage the
	* connection to the Java Virtual Machine indicated by <tt>vmid</tt>.
	*
	* This method provide a convenient short cut for attaching to a specific
	* instrumented Java Virtual Machine. The information in the VmIdentifier
	* is used to construct a corresponding HostIdentifier, which in turn is
	* used to create the MonitoredHost instance.
	*
	* @param vmid The identifier for the target Java Virtual Machine.
	* @return MonitoredHost - The MonitoredHost object needed to attach to
	* the target Java Virtual Machine.
	*
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public static MonitoredHost getMonitoredHost(VmIdentifier vmid)
	throws MonitorException {
	// use the VmIdentifier to construct the corresponding HostIdentifier
	HostIdentifier hostId = new HostIdentifier(vmid);
	return getMonitoredHost(hostId);
	}

	/**
	* Factory method to construct a MonitoredHost instance to manage the
	* connection to the host indicated by <tt>hostId</tt>.
	*
	* @param hostId the identifier for the target host.
	* @return MonitoredHost - The MonitoredHost object needed to attach to
	* the target host.
	*
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public static MonitoredHost getMonitoredHost(HostIdentifier hostId)
	throws MonitorException {
	/*
	* determine the class name to load. If the system property is set,
	* use the indicated class. otherwise, use the default class.
	*/
	String classname = System.getProperty(IMPL_OVERRIDE_PROP_NAME);
	MonitoredHost mh = null;

	synchronized(monitoredHosts) {
	mh = monitoredHosts.get(hostId);
	if (mh != null) {
	if (mh.isErrored()) {
	monitoredHosts.remove(hostId);
	} else {
	return mh;
	}
	}
	}

	hostId = resolveHostId(hostId);

	if (classname == null) {
	// construct the class name
	classname = IMPL_PACKAGE + ".monitor.protocol."
	+ hostId.getScheme() + "." + MONITORED_HOST_CLASS;
	}

	try {
	// run the constructor taking a single String parameter.
	Class<?> c = Class.forName(classname);

	Constructor cons = c.getConstructor(
	new Class[] { hostId.getClass() }
	);

	mh = (MonitoredHost)cons.newInstance(new Object[] { hostId } );

	synchronized(monitoredHosts) {
	monitoredHosts.put(mh.hostId, mh);
	}
	return mh;
	} catch (ClassNotFoundException e) {
	// from Class.forName();
	throw new IllegalArgumentException("Could not find " + classname
	+ ": " + e.getMessage(), e);
	} catch (NoSuchMethodException e) {
	// from Class.getConstructor();
	throw new IllegalArgumentException(
	"Expected constructor missing in " + classname + ": "
	+ e.getMessage(), e);
	} catch (IllegalAccessException e) {
	// from Constructor.newInstance()
	throw new IllegalArgumentException(
	"Unexpected constructor access in " + classname + ": "
	+ e.getMessage(), e);
	} catch (InstantiationException e) {
	throw new IllegalArgumentException(classname + "is abstract: "
	+ e.getMessage(), e);
	} catch (InvocationTargetException e) {
	Throwable cause = e.getCause();
	if (cause instanceof MonitorException) {
	throw (MonitorException)cause;
	}
	throw new RuntimeException("Unexpected exception", e);
	}
	}

	/**
	* Method to resolve unspecified components of the given HostIdentifier
	* by constructing a new HostIdentifier that replaces the unspecified
	* components with the default values.
	*
	* @param hostId the unresolved HostIdentifier.
	* @return HostIdentifier - a resolved HostIdentifier.
	*
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	protected static HostIdentifier resolveHostId(HostIdentifier hostId)
	throws MonitorException {
	String hostname = hostId.getHost();
	String scheme = hostId.getScheme();
	StringBuffer sb = new StringBuffer();

	assert hostname != null;

	if (scheme == null) {
	if (hostname.compareTo("localhost") == 0) {
	scheme = LOCAL_PROTOCOL;
	} else {
	scheme = REMOTE_PROTOCOL;
	}
	}

	sb.append(scheme).append(":").append(hostId.getSchemeSpecificPart());

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

	try {
	return new HostIdentifier(sb.toString());
	} catch (URISyntaxException e) {
	// programming error - HostIdentifier was valid.
	assert false;
	throw new IllegalArgumentException("Malformed URI created: "
	+ sb.toString());
	}
	}

	/**
	* Return the resolved HostIdentifier for this MonitoredHost.
	*
	* @return HostIdentifier - the resolved HostIdentifier.
	*/
	public HostIdentifier getHostIdentifier() {
	return hostId;
	}

	/* ---- Methods to support polled MonitoredHost Implementations ----- */

	/**
	* Set the polling interval for this MonitoredHost.
	*
	* @param interval the polling interval, in milliseconds
	*/
	public void setInterval(int interval) {
	this.interval = interval;
	}

	/**
	* Get the polling interval.
	*
	* @return int - the polling interval in milliseconds for this MonitoredHost
	*/
	public int getInterval() {
	return interval;
	}

	/**
	* Set the last exception encountered while polling this MonitoredHost.
	*
	* @param lastException the last exception encountered;
	*/
	public void setLastException(Exception lastException) {
	this.lastException = lastException;
	}

	/**
	* Get the last exception encountered while polling this MonitoredHost.
	*
	* @return Exception - the last exception occurred while polling this
	* MonitoredHost, or <tt>null</tt> if no exception
	* has occurred or the exception has been cleared,
	*/
	public Exception getLastException() {
	return lastException;
	}

	/**
	* Clear the last exception.
	*/
	public void clearLastException() {
	lastException = null;
	}

	/**
	* Test if this MonitoredHost is in the errored state. If this method
	* returns true, then the Exception returned by getLastException()
	* indicates the Exception that caused the error condition.
	*
	* @return boolean - true if the MonitoredHost instance has experienced
	* an error, or false if it hasn't or if any past
	* error has been cleared.
	*/
	public boolean isErrored() {
	return lastException != null;
	}

	/**
	* Get the MonitoredVm for the given Java Virtual Machine. The default
	* sampling interval is used for the MonitoredVm instance.
	*
	* @param id the VmIdentifier specifying the target Java Virtual Machine.
	* @return MonitoredVm - the MonitoredVm instance for the target Java
	* Virtual Machine.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract MonitoredVm getMonitoredVm(VmIdentifier id)
	throws MonitorException;

	/**
	* Get the MonitoredVm for the given Java Virtual Machine. The sampling
	* interval is set to the given interval.
	*
	* @param id the VmIdentifier specifying the target Java Virtual Machine.
	* @param interval the sampling interval for the target Java Virtual Machine.
	* @return MonitoredVm - the MonitoredVm instance for the target Java
	* Virtual Machine.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract MonitoredVm getMonitoredVm(VmIdentifier id, int interval)
	throws MonitorException;

	/**
	* Detach from the indicated MonitoredVm.
	*
	* @param vm the monitored Java Virtual Machine.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract void detach(MonitoredVm vm) throws MonitorException;

	/**
	* Add a HostListener. The given listener is added to the list
	* of HostListener objects to be notified of MonitoredHost related events.
	*
	* @param listener the HostListener to add.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract void addHostListener(HostListener listener)
	throws MonitorException;

	/**
	* Remove a HostListener. The given listener is removed from the list
	* of HostListener objects to be notified of MonitoredHost related events.
	*
	* @param listener the HostListener to add.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract void removeHostListener(HostListener listener)
	throws MonitorException;

	/**
	* Return the current set of active Java Virtual Machines for this
	* MonitoredHost. The returned Set contains {@link Integer} instances
	* holding the local virtual machine identifier, or <em>lvmid</em>
	* for each instrumented Java Virtual Machine currently available.
	*
	* @return Set - the current set of active Java Virtual Machines associated
	* with this MonitoredHost, or the empty set of none.
	* @throws MonitorException Thrown if monitoring errors occur.
	*/
	public abstract Set<Integer> activeVms() throws MonitorException;
	}

Back to index...