/*
* Copyright (c) 2015, 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.management.spi;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.Set;
import java.util.stream.Collectors;
The PlatformMBeanProvider class defines the abstract service interface that the ManagementFactory will invoke to find, load, and register Platform MBeans. ManagementFactory loads the
installed providers of this service interface and each provides the platform components that defines MXBean or DynamicMBean to be registered in the platform MBeanServer. A PlatformMBeanProvider will implement the getPlatformComponentList() method to return the list of PlatformComponents it provides. /**
* The PlatformMBeanProvider class defines the abstract service interface
* that the {@link java.lang.management.ManagementFactory} will invoke to find,
* load, and register Platform MBeans.
*
* ManagementFactory loads the {@linkplain ServiceLoader#loadInstalled(java.lang.Class)
* installed providers} of this service interface and each provides the
* {@linkplain PlatformComponent platform components} that defines MXBean
* or DynamicMBean to be registered in the platform MBeanServer.
*
* A {@code PlatformMBeanProvider} will implement the {@code getPlatformComponentList()}
* method to return the list of {@code PlatformComponents} it provides.
*/
public abstract class PlatformMBeanProvider {
PlatformComponent models MBeans of a management interface supported by the platform. If a PlatformComponent models a singleton MBean, the
ObjectName pattern must be the canonical name of that singleton MBean. Otherwise, it must be an ObjectName pattern that can be used to query the MBeans for this PlatformComponent registered in a MBeanServer.
The ObjectName pattern serves as a unique key for identifying the instance of PlatformComponent. It is thus illegal for a given PlatformMBeanProvider to export several instance of PlatformComponent with the same ObjectName pattern string.
If two different provider instances export a PlatformComponent for the
same ObjectName pattern, only the PlatformComponent instance of the first
provider will be taken into account.
Type parameters: - <T> – The higher level interface for which the MBeans modeled by this object should be recognized. For instance, for the
Operating System MXBean, this should be
java.lang.management.OperatingSystemMXBean.
/**
* {@code PlatformComponent} models MBeans of a management interface supported
* by the platform.
*
* If a PlatformComponent models a singleton MBean, the {@link #getObjectNamePattern()
* ObjectName pattern} must be the {@link
* javax.management.ObjectName#getCanonicalName() canonical name} of that
* singleton MBean. Otherwise, it must be an ObjectName pattern
* that can be used to query the MBeans for this
* PlatformComponent registered in a {@code MBeanServer}.
* <br>
* The {@link #getObjectNamePattern() ObjectName pattern} serves as a unique
* key for identifying the instance of PlatformComponent. It is thus illegal
* for a given {@link PlatformMBeanProvider} to export several instance of
* PlatformComponent with the same
* {@link #getObjectNamePattern() ObjectName pattern} string.
* <br>
* If two different provider instances export a PlatformComponent for the
* same ObjectName pattern, only the PlatformComponent instance of the first
* provider will be taken into account.
*
* @param <T> The higher level interface for which the MBeans modeled by
* this object should be recognized. For instance, for the {@link
* java.lang.management.ManagementFactory#getOperatingSystemMXBean()
* Operating System MXBean}, this should be {@link
* java.lang.management.OperatingSystemMXBean
* java.lang.management.OperatingSystemMXBean}.
*/
public interface PlatformComponent<T> {
Returns the names of the management interfaces implemented by the MBeans modeled by this PlatformComponent. Implementation Note: When
ManagementFactory.getPlatformMXBean(mxbeanInterface) or
ManagementFactory.getPlatformMXBeans(mxbeanInterface) are invoked, this PlatformComponent instance will match only if the name of the given mxbeanInterface is found in this list. Returns: the names of the management interfaces exported by the MBeans
modeled by this object.
/**
* Returns the names of the management interfaces implemented by the
* MBeans modeled by this {@code PlatformComponent}.
*
* @implNote
* When {@link java.lang.management.ManagementFactory#getPlatformMXBean(java.lang.Class)
* ManagementFactory.getPlatformMXBean(mxbeanInterface)} or {@link
* java.lang.management.ManagementFactory#getPlatformMXBeans(java.lang.Class)
* ManagementFactory.getPlatformMXBeans(mxbeanInterface)} are invoked,
* this PlatformComponent instance will match only if the name of the
* given {@code mxbeanInterface} is found in this list.
*
* @return the names of the management interfaces exported by the MBeans
* modeled by this object.
*/
public Set<String> mbeanInterfaceNames();
A map from ObjectName string to the MBean instance this PlatformComponent creates. Implementation Note: If shouldRegister() is true, this method will be called when the Platform MBeanServer is initialized. By default, this method will also be called by getMBeans(Class), when
ManagementFactory.getPlatformMXBean(mxbeanInterface) or
ManagementFactory.getPlatformMXBeans(mxbeanInterface) are invoked, and when the name of the given mxbeanInterface is contained in the names of management interfaces returned by mbeanInterfaceNames(). Returns: A map with, for each MBean, the ObjectName string as key
and the MBean as value.
/**
* A map from ObjectName string to the MBean instance this
* {@code PlatformComponent} creates.
*
* @implNote
* If {@link #shouldRegister()} is {@code true}, this method
* will be called when the {@link java.lang.management.ManagementFactory
* #getPlatformMBeanServer() Platform MBeanServer} is initialized.
* By default, this method will also be called by {@link
* #getMBeans(java.lang.Class)}, when {@link
* java.lang.management.ManagementFactory#getPlatformMXBean(java.lang.Class)
* ManagementFactory.getPlatformMXBean(mxbeanInterface)} or {@link
* java.lang.management.ManagementFactory#getPlatformMXBeans(java.lang.Class)
* ManagementFactory.getPlatformMXBeans(mxbeanInterface)} are invoked,
* and when the name of the given {@code mxbeanInterface} is contained
* in the names of management interfaces returned by {@link
* #mbeanInterfaceNames()}.
*
* @return A map with, for each MBean, the ObjectName string as key
* and the MBean as value.
*/
public Map<String, T> nameToMBeanMap();
An ObjectName pattern uniquely identifies the MBeans modeled by this PlatformComponent. If this instance models a singleton MBean, this must be the canonical name of that singleton MBean. Returns: An ObjectName pattern uniquely identifies the MBeans
modeled by this instance.
/**
* An ObjectName pattern uniquely identifies the MBeans
* modeled by this {@code PlatformComponent}.
* If this instance models a singleton MBean, this must be
* the {@link
* javax.management.ObjectName#getCanonicalName() canonical name}
* of that singleton MBean.
*
* @return An ObjectName pattern uniquely identifies the MBeans
* modeled by this instance.
*/
public String getObjectNamePattern();
Returns true if this PlatformComponent models a singleton MBean. By default, true is assumed. Returns: true if this instance models a singleton MBean.
/**
* Returns {@code true} if this {@code PlatformComponent} models
* a singleton MBean. By default, {@code true} is assumed.
*
* @return {@code true} if this instance models a singleton MBean.
*/
public default boolean isSingleton() {
return true;
}
Returns true if the MBeans modeled by this PlatformComponent should automatically be registered in the
Platform MBeanServer. By default, true is assumed. Returns: true if the MBeans modeled by this instance should automatically be registered in the Platform MBeanServer.
/**
* Returns {@code true} if the MBeans modeled by this {@code PlatformComponent}
* should automatically be registered in the {@link
* java.lang.management.ManagementFactory#getPlatformMBeanServer()
* Platform MBeanServer}. By default, {@code true} is assumed.
*
* @return {@code true} if the MBeans modeled by this instance should
* automatically be registered in the Platform MBeanServer.
*/
public default boolean shouldRegister() {
return true;
}
The set of interfaces implemented by the MBeans modeled by this PlatformComponent. Implementation Note:
ManagementFactory.getPlatformManagementInterfaces() calls this method to find the management interfaces supported by the platform. Returns: The set of interfaces implemented by the MBeans modeled
by this instance
/**
* The set of interfaces implemented by the MBeans modeled
* by this {@code PlatformComponent}.
*
* @implNote
* {@link java.lang.management.ManagementFactory#getPlatformManagementInterfaces()
* ManagementFactory.getPlatformManagementInterfaces()} calls this
* method to find the management interfaces supported by the platform.
*
* @return The set of interfaces implemented by the MBeans modeled
* by this instance
*/
public Set<Class<? extends T>> mbeanInterfaces();
Return the list of MBeans that implement the given mbeanIntf modeled by this PlatformComponent. This method returns an empty list if no MBean implements the given mbeanIntf. Params: - mbeanIntf – A management interface.
Implementation Note: This method will be called when
ManagementFactory.getPlatformMXBean(mbeanIntf) or
ManagementFactory.getPlatformMXBeans(mbeanIntf) are invoked. By default it first checks whether the specified mbeanIntf name is contained in the returned list from the mbeanInterfaceNames() method. If yes, it proceeds and calls #mbeans().values() and filters out all MBeans which are not instances of the given mbeanIntf. Otherwise, it returns an empty list. Returns: A (possibly empty) list of MBeans implementing the given mbeanIntf.
/**
* Return the list of MBeans that implement the given {@code mbeanIntf}
* modeled by this {@code PlatformComponent}. This method returns an
* empty list if no MBean implements the given {@code mbeanIntf}.
*
* @implNote This method will be called when {@link
* java.lang.management.ManagementFactory#getPlatformMXBean(java.lang.Class)
* ManagementFactory.getPlatformMXBean(mbeanIntf)} or {@link
* java.lang.management.ManagementFactory#getPlatformMXBeans(java.lang.Class)
* ManagementFactory.getPlatformMXBeans(mbeanIntf)} are invoked.
* By default it first checks whether the specified {@code mbeanIntf}
* name is contained in the returned list from the {@link #mbeanInterfaceNames()}
* method. If yes, it proceeds and calls
* {@link #mbeans().values()} and filters out all
* MBeans which are not instances of the given {@code mbeanIntf}.
* Otherwise, it returns an empty list.
*
* @param mbeanIntf A management interface.
* @return A (possibly empty) list of MBeans implementing the given
* {@code mbeanIntf}.
*/
public default <I> List<? extends I> getMBeans(Class<I> mbeanIntf) {
List<I> list;
if (!mbeanInterfaceNames().contains(mbeanIntf.getName())) {
list = Collections.emptyList();
} else {
list = nameToMBeanMap().values().stream()
.filter(mbeanIntf::isInstance)
.map(mbeanIntf::cast)
.collect(Collectors.toList());
}
return list;
}
}
Instantiates a new PlatformMBeanProvider.
Throws: - SecurityException – if the subclass (and calling code) does not have
RuntimePermission("sun.management.spi.PlatformMBeanProvider.subclass")
/**
* Instantiates a new PlatformMBeanProvider.
*
* @throws SecurityException if the subclass (and calling code) does not
* have {@code RuntimePermission("sun.management.spi.PlatformMBeanProvider.subclass")}
*/
protected PlatformMBeanProvider () {
this(checkSubclassPermission());
}
private PlatformMBeanProvider(Void unused) {
}
Returns a list of PlatformComponent instances describing the Platform
MBeans provided by this provider.
Returns: a list of PlatformComponent instances describing the Platform
MBeans provided by this provider.
/**
* Returns a list of PlatformComponent instances describing the Platform
* MBeans provided by this provider.
*
* @return a list of PlatformComponent instances describing the Platform
* MBeans provided by this provider.
*/
public abstract List<PlatformComponent<?>> getPlatformComponentList();
private static Void checkSubclassPermission() {
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new RuntimePermission(PlatformMBeanProvider.class.getName()+".subclass"));
}
return null;
}
}