com.tangosol.net.management

Class MBeanHelper

java.lang.Object

com.tangosol.util.Base

com.tangosol.net.management.MBeanHelper

Direct Known Subclasses:

MBeanConnector

public abstract class MBeanHelper
extends Base

Helper class providing various functionality related to aggregation of attributes and methods exposed by Coherence JMX framework MBeans.

Since:

Coherence 3.3

Author:

gg 2007/01/02

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MBeanHelper.QueryExpFilter Helper class to expose a Filter object as a QueryExp.

Nested classes/interfaces inherited from class com.tangosol.util.Base

Base.LoggingWriter, Base.StackFrame

Field Summary

Fields

Modifier and Type	Field and Description
static Map<String,SimpleType>	SCALAR_SIMPLETYPES A map of scalar SimpleTypes (classes) keyed by the corresponding JMX signatures.
static Map<String,Class>	SCALAR_TYPES A map of scalar types (classes) keyed by the corresponding JMX signatures.

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Constructor Summary

Constructors

Constructor and Description
MBeanHelper()

Method Summary

Modifier and Type	Method and Description
static int	compareKeyList(ObjectName oname1, ObjectName oname2) Compare two global MBean names forcing numeric comparison of the node ID while using string comparison on all other key properties.
static DynamicMBean	createMapAdapterMbean(Map<String,String> mapDescr, Map<String,?> mapValue) Create a DynamicMBean driven by maps containing attribute descriptions and values.
static MBeanReference	ensureSingletonMBean(String sName) Ensure that there is an instance of a local MBean of the specified type registered with the default MBeansServer.
static JMXServiceURL	findJMXServiceUrl(String sDefaultDomain, com.tangosol.internal.net.management.GatewayDependencies deps) Find the JMXServiceURL for the MBeanConnector used by the Coherence JMX framework.
static MBeanServer	findMBeanServer() Find an MBeanServer that Coherence MBeans are registered with.
static MBeanServer	findMBeanServer(String sDefaultDomain) Find an MBeanServer that has the specified default domain name.
static MBeanServer	findMBeanServer(String sDefaultDomain, com.tangosol.internal.net.management.GatewayDependencies deps) Find an MBeanServer that has the specified default domain name.
protected static Method	findMethod(Class clzMBean, MBeanOperationInfo op) Find a Method for the specified MBeanOperationInfo in the specified MBean class or interface.
protected static Method	findMethod(Class clz, String sName, String... asParamTypes) Find a Method with the specified name and parameter types in the specified class.
static String	getDefaultDomain() Return the the default domain name as configured in the Coherence operational configuration descriptor ("default-domain-name" element).
static String	getDescription(Class<?> clzMBeanIface, MBeanInfo info) Retrieve the description for the MBean from the MBean interface annotation.
static String	getDescription(Class clzMBeanIface, MBeanAttributeInfo info) Retrieve a description for a particular attribute by finding a Description annotation on the getter method for the attribute.
static String	getDescription(Class clzMBeanIface, MBeanOperationInfo info) Retrieve a description for the particular MBeanOperationInfo by finding a Description annotation on the corresponding method.
static MBeanNotificationInfo[]	getNotificationInfo(Class<?> clzMBeanIface) Return an MBeanNotificationInfo if a Notification annotation is present on the provided MBean interface.
protected static <A extends Annotation> A	getParameterAnnotation(Method meth, int iParam, Class<A> clzAnno) Retrieve an Annotation for a parameter to a method.
static String	getParameterName(Class clzMBeanIface, MBeanOperationInfo infoOp, MBeanParameterInfo infoParam, int iParam) Retrieve the parameter name for the specified parameter by finding a Description annotation on the corresponding method.
static boolean	hasDomain(String sCanonical) Return true if the Canonical name is prefixed with the domain name.
static boolean	isQuoteRequired(String s) Determine if the string requires quotes.
static String	quote(String s) Create an escape-sequence string that allows for special characters to be included in a JMX ObjectName.
static String	quoteCanonical(String sCanonical) Return a quoted KeyPropertyString or a quoted canonical name.
static void	registerCacheMBean(CacheService service, String sCacheName, String sContext, Map map) Register the specified map with the cluster registry.
static void	registerCacheMBean(NamedCache cache, String sContext) Register the specified NamedCache with the cluster registry.
static void	registerQueryMBeans(String sMBeanServerDomain, String sQuery, String sPrefix, Registry registry) Find all MBeans matching to the specified query at a local MBeanServer and register them with the specified Registry.
static Object	startHttpConnector(int nPort, MBeanServer mbs) Start a com.sun.jdmk.comm.HtmlAdaptorServer, which is a part of the Sun JMX reference implementation.
static JMXConnectorServer	startRmiConnector(String sAddr, int nRegPort, int nConPort, MBeanServer mbs, Map mapEnv) Start a JMXConnectorServer.
static String	stripDomain(String sCanonical) Remove the domain prefix from the canonical name if one exists.
static String	unquote(String s) Convert a string returned from the quote(java.lang.String) method to the original string.
static void	unregisterCacheMBean(CacheService service, String sCacheName) Unregister all managed objects that are related to the specified cache from the registry.
static void	unregisterCacheMBean(String sCacheName, String sContext) Unregister all managed objects related to the given cache name and context from the cluster registry.

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCALAR_TYPES

public static final Map<String,Class> SCALAR_TYPES

A map of scalar types (classes) keyed by the corresponding JMX signatures.

See Also:

JMX 1.2 specification; Chapter 3, Basic Data Types

SCALAR_SIMPLETYPES

public static final Map<String,SimpleType> SCALAR_SIMPLETYPES

A map of scalar SimpleTypes (classes) keyed by the corresponding JMX signatures.

Constructor Detail

MBeanHelper

public MBeanHelper()

Method Detail

getDefaultDomain

public static String getDefaultDomain()

Return the the default domain name as configured in the Coherence operational configuration descriptor ("default-domain-name" element).

Returns:

the default domain name

findMBeanServer

public static MBeanServer findMBeanServer()

Find an MBeanServer that Coherence MBeans are registered with.

Returns:

an existing or a new MBeanServer with the default domain name as configured in the Coherence operational configuration descriptor

findMBeanServer

public static MBeanServer findMBeanServer(String sDefaultDomain)

Find an MBeanServer that has the specified default domain name. If the domain name is not specified, any existing MBeanServer is chosen.

Parameters:

sDefaultDomain - the default domain name

Returns:

an existing or a new MBeanServer with the specified default domain name

findMBeanServer

public static MBeanServer findMBeanServer(String sDefaultDomain,
                                          com.tangosol.internal.net.management.GatewayDependencies deps)

Find an MBeanServer that has the specified default domain name. If the domain name is not specified, any existing MBeanServer is chosen.

Parameters:

sDefaultDomain - the default domain name

deps - the GatewayDependencies containing the management configuration to use

Returns:

an existing or a new MBeanServer with the specified default domain name

findJMXServiceUrl

public static JMXServiceURL findJMXServiceUrl(String sDefaultDomain,
                                              com.tangosol.internal.net.management.GatewayDependencies deps)

Find the JMXServiceURL for the MBeanConnector used by the Coherence JMX framework.

Parameters:

sDefaultDomain - the default domain name

deps - the GatewayDependencies containing the management configuration to use

Returns:

JMXServiceUrl for the MBeanConnector or null if no Connector is running.

registerQueryMBeans

public static void registerQueryMBeans(String sMBeanServerDomain,
                                       String sQuery,
                                       String sPrefix,
                                       Registry registry)

Find all MBeans matching to the specified query at a local MBeanServer and register them with the specified Registry.

Note: the MBeanServer that the query runs against is not necessarily the one used by the Registry.

Parameters:

sMBeanServerDomain - the default domain of the MBeanServer where the query should be executed. If this value is empty or null the Coherence default domain is used

sQuery - a JMX query string that will be used to find the MBeans

sPrefix - a target location to prepend to converted MBean names

registry - a Registry to register the JMX query results with

registerCacheMBean

public static void registerCacheMBean(NamedCache cache,
                                      String sContext)

Register the specified NamedCache with the cluster registry.

Parameters:

cache - the NamedCache object to register

sContext - the cache context (tier)

registerCacheMBean

public static void registerCacheMBean(CacheService service,
                                      String sCacheName,
                                      String sContext,
                                      Map map)

Register the specified map with the cluster registry.

Parameters:

service - the CacheService that the cache belongs to

sCacheName - the cache name

sContext - the cache context (tier)

map - the map object to register

unregisterCacheMBean

public static void unregisterCacheMBean(CacheService service,
                                        String sCacheName)

Unregister all managed objects that are related to the specified cache from the registry.

Parameters:

service - the CacheService that the cache belongs to

sCacheName - the cache name

unregisterCacheMBean

public static void unregisterCacheMBean(String sCacheName,
                                        String sContext)

Unregister all managed objects related to the given cache name and context from the cluster registry.

Parameters:

sCacheName - the cache name

sContext - the cache context (tier)

ensureSingletonMBean

public static MBeanReference ensureSingletonMBean(String sName)

Ensure that there is an instance of a local MBean of the specified type registered with the default MBeansServer.

Parameters:

sName - an MBean name

Returns:

the MBeanReference for the registered MBean

createMapAdapterMbean

public static DynamicMBean createMapAdapterMbean(Map<String,String> mapDescr,
                                                 Map<String,?> mapValue)

Create a DynamicMBean driven by maps containing attribute descriptions and values.

Parameters:

mapDescr - Map<String, String> keyed by the attribute names with values being attribute descriptions

mapValue - Map<String, Object> keyed by the attribute names with values being attribute values

startRmiConnector

public static JMXConnectorServer startRmiConnector(String sAddr,
                                                   int nRegPort,
                                                   int nConPort,
                                                   MBeanServer mbs,
                                                   Map mapEnv)

Start a JMXConnectorServer. This method is used to expose the specified MBeanServer to external agents (such as JConsole) using RMI.

This method also allows for the RMI functionality to emulate the JConsole remote connection security.

For the list of relevant system properties please see: Java 1.6 Agent Documentation.

Parameters:

sAddr - host to bind to

nRegPort - port used for the JMX RMI registry

nConPort - port used for the JMX RMI connection

mbs - MBeanServer that contains Coherence MBeans

mapEnv - a set of attributes to control the new connector server's behavior

Returns:

a JMXConnectorServer that has been started

See Also:

JMXConnectorServerFactory

startHttpConnector

public static Object startHttpConnector(int nPort,
                                        MBeanServer mbs)

Start a com.sun.jdmk.comm.HtmlAdaptorServer, which is a part of the Sun JMX reference implementation. It is being created via reflection to avoid a runtime dependency to this library.

Parameters:

nPort - port to bind the HTTP server to

mbs - MBeanServer that this HTTP server will expose

Returns:

an HtmlAdaptorServer that has been started

quote

public static String quote(String s)

Create an escape-sequence string that allows for special characters to be included in a JMX ObjectName.

Parameters:

s - the string to be quoted

Returns:

the quoted string

Since:

Coherence 3.4

unquote

public static String unquote(String s)

Convert a string returned from the quote(java.lang.String) method to the original string.

Parameters:

s - the string to be unquoted

Returns:

the unquoted string

Throws:

IllegalArgumentException - if the passed string could not have been returned by the quote(java.lang.String) method; for instance if it does not begin and end with a quote (")

Since:

Coherence 3.4

isQuoteRequired

public static boolean isQuoteRequired(String s)

Determine if the string requires quotes.

Parameters:

s - the string to be quoted

Returns:

true iff the quote(java.lang.String) method needs to be called

Since:

Coherence 3.4

quoteCanonical

public static String quoteCanonical(String sCanonical)
                             throws MalformedObjectNameException

Return a quoted KeyPropertyString or a quoted canonical name.

Parameters:

sCanonical - a string to be quoted

Returns:

a quoted and escape-sequence string

Throws:

MalformedObjectNameException - if the name is invalid

Since:

Coherence 3.4

hasDomain

public static boolean hasDomain(String sCanonical)

Return true if the Canonical name is prefixed with the domain name.

Parameters:

sCanonical - a canonical MBean name or key property list

Returns:

true iff the name contains the domain prefix

Since:

Coherence 3.6

stripDomain

public static String stripDomain(String sCanonical)

Remove the domain prefix from the canonical name if one exists.

Parameters:

sCanonical - a canonical MBean name or key property list

Returns:

the canonical name stripped of the domain prefix

Since:

Coherence 3.6

compareKeyList

public static int compareKeyList(ObjectName oname1,
                                 ObjectName oname2)

Compare two global MBean names forcing numeric comparison of the node ID while using string comparison on all other key properties. For example, the following order is enforced:

   Coherence:type=Node,nodeId=2 < Coherence:type=Node,nodeId=10
   Coherence:type=Cache,nodeId=20 < Coherence:type=Node,nodeId=1
 

If the key sets are different the lexicographical comparison is used.

Parameters:

oname1 - the first ObjectName to be compared

oname2 - the second ObjectName to be compared

Returns:

a negative integer, zero, or a positive integer as the first name is less than, equal to, or greater than the second one

Since:

Coherence 3.6

getDescription

public static String getDescription(Class<?> clzMBeanIface,
                                    MBeanInfo info)

Retrieve the description for the MBean from the MBean interface annotation.

Parameters:

clzMBeanIface - the MBean interface

info - the MBeanInfo for the MBean

Returns:

the MBean description

Since:

Coherence 12.1.2

getDescription

public static String getDescription(Class clzMBeanIface,
                                    MBeanAttributeInfo info)

Retrieve a description for a particular attribute by finding a Description annotation on the getter method for the attribute. If a description is not found on the getter method, the setter will be checked.

Parameters:

clzMBeanIface - the MBean interface

info - the MBeanAttributeInfo for the attribute

Returns:

the description for an attribute

Since:

Coherence 12.1.2

getDescription

public static String getDescription(Class clzMBeanIface,
                                    MBeanOperationInfo info)

Retrieve a description for the particular MBeanOperationInfo by finding a Description annotation on the corresponding method.

Parameters:

clzMBeanIface - the MBean interface

info - the MBeanOperationInfo

Returns:

the description for an operation

Since:

Coherence 12.1.2

getParameterName

public static String getParameterName(Class clzMBeanIface,
                                      MBeanOperationInfo infoOp,
                                      MBeanParameterInfo infoParam,
                                      int iParam)

Retrieve the parameter name for the specified parameter by finding a Description annotation on the corresponding method.

Parameters:

clzMBeanIface - the MBean interface

infoOp - the MBeanOperationInfo for the op

infoParam - the MBeanParameterInfo for the parameter

iParam - zero-based sequence number of the parameter

Returns:

the name to use for the given parameter

Since:

Coherence 12.1.2

getNotificationInfo

public static MBeanNotificationInfo[] getNotificationInfo(Class<?> clzMBeanIface)

Return an MBeanNotificationInfo if a Notification annotation is present on the provided MBean interface.

Parameters:

clzMBeanIface - the MBean interface

Returns:

an array of MBeanNotificationInfo of size 0 or 1 based on the presence of a Notification annotation.

getParameterAnnotation

protected static <A extends Annotation> A getParameterAnnotation(Method meth,
                                                                 int iParam,
                                                                 Class<A> clzAnno)

Retrieve an Annotation for a parameter to a method.

Type Parameters:

A - the Annotation sub type

Parameters:

meth - the Method

iParam - zero-based index of the parameter

clzAnno - the Annotation Class to be retrieved

Returns:

the annotation or null if no Annotation is found

findMethod

protected static Method findMethod(Class clzMBean,
                                   MBeanOperationInfo op)

Find a Method for the specified MBeanOperationInfo in the specified MBean class or interface.

Parameters:

clzMBean - the MBean class (interface)

op - the MBeanOperationInfo

Returns:

the Method or null if no method is found

findMethod

protected static Method findMethod(Class clz,
                                   String sName,
                                   String... asParamTypes)

Find a Method with the specified name and parameter types in the specified class.

Parameters:

clz - the class (interface)

sName - the Method name

asParamTypes - the array of Strings representing parameter types

Returns:

the Method or null if no method is found