The Carbon Java Framework  

The Carbon Management Module

Management & JMX Usage

Author: Greg Hinkle (ghinkl at sapient.com)
Version: $Revision: 1.4 $($Author: ghinkl $ / $Date: 2003/04/04 01:11:59 $)
Created: April 2002

Introduction

The Management and JMX services within Carbon are intended to provide a degree of transparency to large enterprise applications. While their use does add complication it also offers the chance to provide a more maintainable and robust solution while decreasing the cost of implementing administration functionality.

These described services in Carbon are built on the Java standard JMX specification(?) and use this standard to remain compatible with and opened to other tools and application servers on the market. Many of the application servers already have built-in JMX services today or plan to in the near future.

The design of these services is such that there exists one MBeanServerService component that provides access to the MBean Server services of either the underlying application server or one that is deployed with Carbon. When deploying to Weblogic, for example, it makes sense to configure an service that provides access to the underlying Weblogic JMX server. By using the included MBean Assistant, every Carbon Component in the system can automatically be registered with this server and be exposed for management.

Exposing an component as an MBean for management means that you can access class member attributes in a running server, execute methods against that class or even listen for certain events called notifications. These benefits are designed to be easily extended to new Carbon Components written for projects and therefore only require the creation of one XML file for each new component. The exposing of useful and interesting operations and information is recommended for those building Carbon Components.

MBean Server Services

The MBean Server services are a Carbon Component interface that is designed to simply return a reference to a specific JMX MBeanServer (?).

Configuring

An MBeanServerService is configured like any other component in the system. The default is normally placed at the component name: /manage/DefaultMBeanServer. Below are the configurations for use with the MX4J open source JMX Server and the Weblogic Server JMX services respectively.

MX4J Server Configuration

<Configuration 
  ConfigurationInterface="org.sape.carbon.core.component.ComponentConfiguration">

  <FunctionalImplementationClass>
    org.sape.carbon.services.jmx.server.mx4j.Mx4jMBeanServerService
  </FunctionalImplementationClass>
  <FunctionalInterface>
    org.sape.carbon.services.jmx.server.MBeanServerService
  </FunctionalInterface>

</Configuration>

The basic configuration for Weblogic will connect the MBean server using the default InitialContext. This will use the principal and credential supplied to Weblogic upon startup.

Default Weblogic Server Configuration

<Configuration
  ConfigurationInterface="org.sape.carbon.core.component.ComponentConfiguration">

  <FunctionalImplementationClass>
    org.sape.carbon.services.jmx.server.weblogic.WebLogicMBeanServerServiceImpl
  </FunctionalImplementationClass>
  <FunctionalInterface>
    org.sape.carbon.services.jmx.server.MBeanServerService
  </FunctionalInterface>

</Configuration>

To provide a different principal and credential to connect to the Weblogic MBean Server use the component specific configuration. The principal needs to be a member of the "Administrators" group within Weblogic to have access to the MBean server.

Weblogic Server Configuration

<Configuration
  ConfigurationInterface="org.sape.carbon.services.jmx.server.weblogic.WebLogicMBeanServerServiceConfigurationn">

  <FunctionalImplementationClass>
    org.sape.carbon.services.jmx.server.weblogic.WebLogicMBeanServerServiceImpl
  </FunctionalImplementationClass>
  <FunctionalInterface>
    org.sape.carbon.services.jmx.server.MBeanServerService
  </FunctionalInterface>

  <Principal>username</Principal>
  <Credentials>password</Credentials>

</Configuration>

Management Interceptor

The Management Interceptor is designed to expose the JMX face of a component to make it extremely easy to manage a Carbon Component through JMX. The interceptor provides a custom implementation of the JMX DynamicMBean interface providing attributes, operations and notification information for a Carbon Component. This information is easily exposed by creating an XML document for the interface of the component you would like to expose. The power of this system is that the Management Assistant is able to aggregate the JMX views of each part of a component into a single, unified interface, much like the Carbon Component system does with the additional functionality provided by decorators.

Automatically, each component exposes lifecycle information and methods that can be used to monitor the state of all Carbon Components in a system. Configuration controls are also include, giving you the ability to read and alter server configuration while the system is running. In addition, by simply turning on the included statistics interceptor, Carbon exposes information about the usage of all components through JMX. And by providing further more detailed information specific to the component, you can create a powerful remote management system that provides real-time information and control over your entire application.

Configuring the Component Template

In order to turn on the Management Interceptor so that a Carbon Component is registered with an MBeanServer, simply add the following to the ComponentTemplat configuration used by the component. (The default is in the configuration location: /core/ComponentTemplate).

Management Interceptor Configuration

<DecoratorConfiguration>
   <Factory>org.sape.carbon.services.management.interceptor.ManagementInterceptorFactory</Factory>
</DecoratorConfiguration>

Creating a new MBean Information XML document

In order to add methods or attributes to the set of things exposed for a component, you must provide the system with a XML descriptor with that information. These documents must have the same name as the class that they are describing and must be placed in the config location: /manage/info.

JMX is designed to be an interface for common management. It is designed to separate the concerns of handling management from providing control and access to those managed beans. To allow management services to work, there is a limited capability for the types of information that can be accessed. Though interfaces can be designed with complex, user-defined types, you may end up being limited by the capabilities of the management application and the types that it can handle. A good practice is to stick to primitive types and their object counterparts.

MRUCache JMX descriptor document example

<?xml version = "1.0" encoding = "UTF-8"?>
<Configuration
  ConfigurationInterface="org.sape.carbon.services.management.interceptor.MBeanInfoConfiguration">
    <Type>org.sape.carbon.services.cache.mru.MRUCache</Type>
    <Description>This component provides the basic MRU cache capabilities.</Description>

    <Attributes>
        <Name>Hits</Name>
        <Description>The count of cache hits.</Description>
        <Type>java.lang.Long</Type>
        <Is>false</Is>
        <Writable>false</Writable>
        <Readable>true</Readable>
    </Attributes>

    <Attributes>
        <Name>Misses</Name>
        <Description>The count of cache misses.</Description>
        <Type>java.lang.Long</Type>
        <Is>false</Is>
        <Writable>false</Writable>
        <Readable>true</Readable>
    </Attributes>

    <Attributes>
        <Name>HitPercentage</Name>
        <Description>The percent of lookups that were cache hits</Description>
        <Type>java.lang.Float</Type>
        <Is>false</Is>
        <Writable>false</Writable>
        <Readable>true</Readable>
    </Attributes>

    <Attributes>
        <Name>Size</Name>
        <Description>The current number of items in this cache.</Description>
        <Type>java.lang.Long</Type>
        <Is>false</Is>
        <Writable>false</Writable>
        <Readable>true</Readable>
    </Attributes>

    <Operations>
        <Name>entrySet</Name>
        <Description>Returns the set of all cached values.</Description>
        <ReturnType>java.lang.Set</ReturnType>
        <Impact>Info</Impact>
    </Operations>

</Configuration>

Remote Administration

Remote administration can happen in a number of ways. Although future specifications will create a standard way of remote JMX access, for now there are custom ways for accessing all JMX Servers on the market. Nearly all JMX Servers provide a web interface and many can be accessed using the MC4J management console available at: http://mc4j.sf.net.

Remoting Server for MX4J

If you are running Carbon with the MX4J server and wish to access it remotely, you must configure the Remote Admin Server service (typically in the configuration location: /manage/RemoteAdminServer) and add it to the startup service (/core/StartupService).

MX4J Remote Admin Server Configuration

<Configuration ConfigurationInterface="org.sape.carbon.services.jmx.server.mx4j.JrmpRemotingConfiguration">

    <FunctionalInterface>
      org.sape.carbon.services.jmx.server.MBeanServerService
    </FunctionalInterface>
    <FunctionalImplementationClass>
      org.sape.carbon.services.jmx.server.mx4j.DefaultJrmpRemotingImpl
    </FunctionalImplementationClass>

    <MBeanServerService>ref:///manage/DefaultMBeanServer</MBeanServerService>

    <ComponentTemplateName>/core/ComponentTemplate</ComponentTemplateName>

    <Port>1099</Port>
    <InitialContextFactoryClass>com.sun.jndi.rmi.registry.RegistryContextFactory</InitialContextFactoryClass>
    <Hostname>localhost</Hostname>

</Configuration>

Startup Service Configuration

<!-- This is the management server available via JRMP -->
<StartupComponent
  ConfigurationInterface="org.sape.carbon.core.component.startup.StartupServiceConfiguration$StartupComponentConfiguration">

    <ComponentName>/manage/RemoteAdminServer</ComponentName>
    <Enabled>true</Enabled>
</StartupComponent>

Appendices

Definitions

TermDefinition
JMX The Java Management Extensions specification. For more details see: http://java.sun.com/products/JavaManagement/index.html
MBean MBean is the JMX terminology for a "Managed Bean" or any Java Object that has a JMX representation and is registered with an MBean Server.
MBeanServer An MBeanServer is the main JMX controlling object in a system. Its job is to hold references to all the MBeans in a particular set of "Domains" (named groupings).
Copyright © 2001-2003, Sapient Corporation