https://openjdk.java.net/ 
/*
 * 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.URISyntaxException;
import java.util.HashMap;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.Set;

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 MonitoredVm instances. Concrete implementations of this class provide methods for managing the communications protocols and provide for event notification. 
Author:Brian Doherty
See Also:
Since:1.5
/**
 * 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 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 HostIdentifier for this MonitoredHost instance.

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

    
The polling interval, in milliseconds, for this MonitoredHost instance.

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

    
The last Exception encountered while polling this MonitoredHost.

/**
     * 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 hostIdString 
Params:
Throws:
  • MonitorException –  Thrown if monitoring errors occur.
  • URISyntaxException – Thrown when the hostIdString is poorly
                           formed. This exception may get encapsulated
                           into MonitorException in a future revision.
Returns:MonitoredHost - the MonitoredHost instance for communicating
                        with the indicated host using the protocol
                        specified in hostIdString.
/**
     * Factory method to construct MonitoredHost instances to manage
     * connections to the host indicated by {@code hostIdString}
     *
     * @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 vmid. 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. 
Params:
  • vmid – The identifier for the target Java Virtual Machine.
Throws:
Returns:MonitoredHost - The MonitoredHost object needed to attach to
                        the target Java Virtual Machine.
/**
     * Factory method to construct a MonitoredHost instance to manage the
     * connection to the Java Virtual Machine indicated by {@code vmid}.
     *
     * 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);
    }


    /*
     * Load the MonitoredHostServices
     */
    private static ServiceLoader<MonitoredHostService> monitoredHostServiceLoader =
        ServiceLoader.load(MonitoredHostService.class, MonitoredHostService.class.getClassLoader());

    
Factory method to construct a MonitoredHost instance to manage the connection to the host indicated by hostId. 
Params:
  • hostId – the identifier for the target host.
Throws:
Returns:MonitoredHost - The MonitoredHost object needed to attach to
                        the target host.
/**
     * Factory method to construct a MonitoredHost instance to manage the
     * connection to the host indicated by {@code hostId}.
     *
     * @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 {
        MonitoredHost mh = null;

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

        hostId = resolveHostId(hostId);

        for (MonitoredHostService mhs : monitoredHostServiceLoader) {
            if (mhs.getScheme().equals(hostId.getScheme())) {
                mh = mhs.getMonitoredHost(hostId);
            }
        }

        if (mh == null) {
            throw new IllegalArgumentException("Could not find MonitoredHost for scheme: " + hostId.getScheme());
        }

        synchronized(monitoredHosts) {
            monitoredHosts.put(mh.hostId, mh);
        }

        return mh;
    }

    
Method to resolve unspecified components of the given HostIdentifier
by constructing a new HostIdentifier that replaces the unspecified
components with the default values.

Params:
  • hostId – the unresolved HostIdentifier.
Throws:
Returns:HostIdentifier - a resolved HostIdentifier.
/**
     * 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();
        StringBuilder sb = new StringBuilder();

        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.

Returns:HostIdentifier - the resolved HostIdentifier.
/**
     * 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.

Params:
  • interval – the polling interval, in milliseconds
/**
     * 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.

Returns:int - the polling interval in milliseconds for this MonitoredHost
/**
     * 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.

Params:
  • lastException – the last exception encountered;
/**
     * 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.

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

    
Clear the last exception.

/**
     * 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.

Returns:boolean - true if the MonitoredHost instance has experienced
                  an error, or false if it hasn't or if any past
                  error has been cleared.
/**
     * 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.

Params:
  • id – the VmIdentifier specifying the target Java Virtual Machine.
Throws:
Returns:MonitoredVm - the MonitoredVm instance for the target Java
                      Virtual Machine.
/**
     * 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.

Params:
  • id – the VmIdentifier specifying the target Java Virtual Machine.
  • interval – the sampling interval for the target Java Virtual Machine.
Throws:
Returns:MonitoredVm - the MonitoredVm instance for the target Java
                      Virtual Machine.
/**
     * 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.

Params:
  • vm – the monitored Java Virtual Machine.
Throws:
/**
     * 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.

Params:
  • listener – the HostListener to add.
Throws:
/**
     * 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.

Params:
  • listener – the HostListener to add.
Throws:
/**
     * 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 Integer instances holding the local virtual machine identifier, or lvmid
for each instrumented Java Virtual Machine currently available.

Throws:
Returns:Set - the current set of active Java Virtual Machines associated
              with this MonitoredHost, or the empty set of none.
/**
     * 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;
}