Package 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

  • Field Details

  • Constructor Details

    • MBeanHelper

      public MBeanHelper()

  • Method Details

    • getDefaultDomain

      public static String getDefaultDomain()
      Return the default domain name as configured in the Coherence operational configuration descriptor ("default-domain-name" element).
      Returns:
      the default domain name

    • checkReadOnly

      public static void checkReadOnly(String sOperation)
      Checks whether "write" operations are allowed.
      Throws:
      SecurityException - if the model is "read-only"

    • 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

    • registerViewMBean

      public static void registerViewMBean(ContinuousQueryCache cache)
      Register the specified view cache with the cluster registry.
      Parameters:
      cache - the ContinuousQueryCache to register

    • registerViewMBean

      public static void registerViewMBean(CacheService service, ContinuousQueryCache cache)
      Register the specified view cache with the cluster registry.
      Parameters:
      service - the CacheService that the cache belongs to
      cache - the cache object to register

    • unregisterViewMBean

      public static void unregisterViewMBean(NamedCache cache)
      Unregister all managed objects related to the given view cache and context from the cluster registry.
      Parameters:
      cache - the cache

    • unregisterViewMBean

      public static void unregisterViewMBean(Cluster cluster, String sServiceName, String sCacheName)
      Unregister all managed objects related to the given view cache and context from the cluster registry.
      Parameters:
      cluster - the Cluster object
      sServiceName - the CacheService that the cache belongs to
      sCacheName - the cache name

    • 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 sServiceName, String sCacheName, String sContext)
      Unregister all managed objects that are related to the specified cache from the registry.
      Parameters:
      sServiceName - the CacheService name
      sCacheName - the cache name
      sContext - the cache context (tier)

    • unregisterCacheMBean

      public static void unregisterCacheMBean(CacheService service, String sCacheName, String sContext)
      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
      sContext - the cache context (tier)

    • unregisterCacheMBean

      public static void unregisterCacheMBean(Cluster cluster, String sServiceName, String sCacheName, String sContext)
      Unregister all managed objects that are related to the specified cache from the registry.
      Parameters:
      cluster - the Cluster object
      sServiceName - the CacheService that the cache belongs to
      sCacheName - the cache name
      sContext - the cache context (tier)

    • 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)

    • unregisterCacheMBean

      public static void unregisterCacheMBean(NamedCache cache, String sContext)
      Unregister all managed objects related to the given cache name and context from the cluster registry.
      Parameters:
      cache - the cache
      sContext - the cache context (tier)

    • registerPagedTopicMBean

      public static void registerPagedTopicMBean(PagedTopicService service, String sTopicName)
      Register the specified PagedTopic with the cluster registry.
      Parameters:
      service - the PagedTopic Service that the topic belongs to
      sTopicName - the name of the topic to register

    • unregisterPagedTopicMBean

      public static void unregisterPagedTopicMBean(Service service, NamedTopic<?> topic)
      Unregister all managed objects related to the given topic name from the cluster registry.
      Parameters:
      service - the topic service
      topic - the topic

    • unregisterPagedTopicMBean

      public static void unregisterPagedTopicMBean(Service service, String sTopicName)
      Unregister all managed objects related to the given topic name from the cluster registry.
      Parameters:
      service - the topic service
      sTopicName - the topic name

    • getTopicMBeanName

      public static String getTopicMBeanName(NamedTopic<?> topic)
      Return the MBean name for the topic.

      The name returned will be the generic name without the member's nodeId key.

      Parameters:
      topic - the topic to obtain the MBean name for
      Returns:
      the MBean name for the topic

    • getTopicMBeanPattern

      public static String getTopicMBeanPattern(TopicService service)
      Return the MBean name pattern that will match all topic MBeans for the service.

      The name returned will be the generic name without the member's nodeId key.

      Parameters:
      service - the topic to service
      Returns:
      the MBean name for the topic

    • getTopicMBeanPattern

      public static String getTopicMBeanPattern()
      Return the MBean name pattern that will match all topic MBeans.

      The name returned will be the generic name without the member's nodeId key.

      Returns:
      the MBean name for the topic

    • registerSubscriberGroupMBean

      public static void registerSubscriberGroupMBean(PagedTopicService service, com.tangosol.internal.net.topic.impl.paged.model.PagedTopicSubscription subscription)
      Register the specified PagedTopic subscriber group with the cluster registry.
      Parameters:
      service - the topic Service that the topic belongs to
      subscription - the subscription

    • unregisterSubscriberGroupMBean

      public static void unregisterSubscriberGroupMBean(PagedTopicService service, com.tangosol.internal.net.topic.impl.paged.model.PagedTopicSubscription subscription)
      Unregister all managed objects related to the given topic subscriber group name from the cluster registry.
      Parameters:
      service - the topic Service that the topic belongs to
      subscription - the subscription

    • getSubscriberGroupMBeanName

      public static String getSubscriberGroupMBeanName(com.tangosol.internal.net.topic.impl.paged.model.SubscriberGroupId id, String sTopicName, Service service)
      Return the MBean name for a subscriber group.

      The name returned will be the generic name without the member's nodeId key.

      Parameters:
      id - the SubscriberGroupId
      sTopicName - the name of the topic
      service - the service owning the topic
      Returns:
      the MBean name for a subscriber group

    • registerSubscriberMBean

      public static void registerSubscriberMBean(com.tangosol.internal.net.topic.impl.paged.PagedTopicSubscriber<?> subscriber)
      Register the specified PagedTopic subscriber with the cluster registry.
      Parameters:
      subscriber - the topic subscriber

    • unregisterSubscriberMBean

      public static void unregisterSubscriberMBean(com.tangosol.internal.net.topic.impl.paged.PagedTopicSubscriber<?> subscriber)
      Unregister all managed objects related to the given topic subscriber from the cluster registry.
      Parameters:
      subscriber - the topic subscriber

    • getSubscriberMBeanName

      public static String getSubscriberMBeanName(com.tangosol.internal.net.topic.impl.paged.PagedTopicSubscriber subscriber)
      Return the MBean name for a PagedTopicSubscriber.
      Parameters:
      subscriber - the PagedTopicSubscriber
      Returns:
      the MBean name for a PagedTopicSubscriber

    • getSubscriberMBeanPattern

      public static String getSubscriberMBeanPattern(NamedTopic<?> topic, boolean fLocalOnly)
      Return the MBean name pattern for all subscribers in a topic.
      Parameters:
      topic - the NamedTopic
      Returns:
      the MBean name pattern for all subscribers in a topic

    • getSubscriberMBeanPattern

      public static String getSubscriberMBeanPattern(NamedTopic<?> topic, com.tangosol.internal.net.topic.impl.paged.model.SubscriberGroupId groupId, boolean fLocalOnly)
      Return the MBean name pattern for all subscribers in a subscriber group for topic.
      Parameters:
      topic - the NamedTopic
      Returns:
      the MBean name pattern for all subscribers in a subscriber group for a topic

    • 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
      Returns:
      a DynamicMBean

    • 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:

    • 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

    • quote

      protected static String quote(String s, boolean fKey)
      Create an escape-sequence string that allows for special characters to be included in a JMX ObjectName.
      Parameters:
      s - the string to be quoted
      fKey - true if a key in the ObjectName is being quoted
      Returns:
      the quoted string
      Since:
      12.2.1.4

    • safeUnquote

      public static String safeUnquote(String s)
      Unquote a string iff given string is quoted otherwise return original string.
      Parameters:
      s - the string
      Returns:
      the unquoted string
      Since:
      12.2.1.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

    • isQuoteRequired

      public static boolean isQuoteRequired(String s, boolean fKey)
      Determine if the string requires quotes.
      Parameters:
      s - the string to be quoted
      fKey - true if a key in the ObjectName is being 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. Wildcard and AnyCharacter (* and ? respectively) are not escaped when present on the value of a key value pair.
      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

    • ensureDomain

      public static String ensureDomain(String sCanonical)
      Ensure the Canonical name is prefixed with the domain name.
      Parameters:
      sCanonical - a canonical MBean name or key property list
      Returns:
      a Canonical name that is prefixed with the domain name.
      Since:
      Coherence 12.2.1.4

    • 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

    • isNonMemberMBean

      public static boolean isNonMemberMBean(String sName)
      Returns true if the specified MBean name is a non-member specific name.
      Parameters:
      sName - the MBean name to test
      Returns:
      true if the specified MBean name is a non-member specific name