Overview

This page is a design doc on how to present a ProfileService ManagementView of the resources managed by the AS ChannelFactory. Comments are welcome.

See JGroups ChannelFactory and Shared Transport in JBoss AS 5for background on the usage and function of the ChannelFactory. Suffice it to say that it is the central point for configuring and managing JGroups Channels in AS 5+. As such it is an important resource that should expose a nice interface via the ProfileService ManagementView.

Management of JGroups configurations by a tool can be cumbersome because:

1) In AS 4.x the relevant configuration was a done via passing an XML element as the value for a -service.xml attribute for some service (e.g. a JBoss Cache) that needed the channel. XML inside XML, with that XML possibly appearing in arbitrary locations.

2) JGroups configs use a custom XML format.

The ChannelFactory helps with both of these since:

1) It centralizes the configuration to one service.

2) That service can handle converting information between the JGroups format and the ManagedObject classes used by the ProfileService ManagementView.

Following is a discussion of the intended management interface for the ChannelFactory.

Accessing the ManagedComponent for the ChannelFactory

@ManagementObject(name="JGroupsChannelFactory", 
      componentType=@ManagementComponent(type="MCBean", subtype="JGroupsChannelFactory"),
      properties=ManagementProperties.EXPLICIT,
      isRuntime=true)
public class JChannelFactory
      implements ChannelFactory, JChannelFactoryMBean, MBeanRegistration

Information on Running Channels

The ChannelFactory will maintain a reference to a channels it has created and not yet closed. It will expose these via a read-only ManagedProperty openChannels. The value of this property will have the following structure:

Type: CollectionMetaValue (representing a Set)

Element Type: CompositeMetaValue (representing a Channel)

Structure of the CompositeMetaValue:

• id: SimpleMetaValue with the id passed by client when it requested the channel. May be null, as the client doesn't have to pass an id param. Option: if null, return the clusterName value.
• clusterName: SimpleMetaValue with the value of the Channel.getClusterName() property. The string shared by all channels in the cluster that form a logical group.
• stackName: SimpleMetaValue with the name of the protocol stack configuration that was used to create the channel. May be null as the ChannelFactory can create channels via other mechanisms.
• protocolStackConfiguration: See discussion below of MetaValue representation of a protocol stack configuration.
• channelObjectName: if the factory is configured to register channels in JMX, SimpleMetaValue with the string form of the ObjectName of the mbean that represents the channel. The MBean for a channel exposes a number of attributes and operations. Any alteration by a management tool of the runtime state of a Channel would be via these MBeans.
  
• protocolObjectNames: if the factory is configured to register protocols in JMX, CollectionMetaValue whose elements are SimpleMetaValues with the string form of the ObjectName of the mbeans that each represent one of the channel's protocols. The MBean for a protocol exposes a number of attributes and operations. Any alteration by a management tool of the runtime state of a protocol would be via these MBeans.
• localAddress: SimpleMetaValue wrapping Channel.getLocalAddress().toString()
• currentView: the current view. See discussion below of MetaValue representation of a protocol stack configuration.

The piece that is conceptually missing is tying together the information on a running JGroups Channel with information on the service that is using it.  A managment tool can use some "black art" to help with this. The standard uses of a JGroups Channel in the AS are for 1) HAPartition, 2) JBoss Cache and 3) JBM. A tool that understands how those services use JGroups can probably match channels to their consuming services, if those services expose the necessary configuration data.

Information on Registered Protocol Stack Configurations

The ChannelFactory maintains a registry of named JGroups protocol stack configurations. Typically apps request a Channel by specifying the name of the desired configuration. The management interface will expose this registry via property protocolStackConfigurations. The key thing here is this will be a read-write property, with any changes persisted via the ProfileService attachment persistence mechanism. (As with other ProfileService ManagementView configuration changes, the underlying JGroups-format -stacks.xml file that serves as a source of raw configuration will not be updated.) Note that updating the registry of protocol stack configurations will not affect the operation of pre-existing channels created from the updated stack.

The value returned by the protocolStackConfigurations property will be a CompositeMetaValue. Structure is as follows

• name: SimpleMetaValue with name of the protocol stack. Will not be null.
• description: any text description of the configuration provided in the -stacks.xml. May be null.
• configuration: See discussion below of MetaValue representation of a protocol stack configuration.

Information on the ChannelFactory Itself

TODO: list the misc management properties exposed by ChannelFactory

MetaValue Representation of a Protocol Stack Configuration

A protocol stack is a...stack, so naturally its configuration is represented as CollectionMetaValue, with one element for each protocol. Each element is a CompositeMetaValue, with the following structure:

• name: SimpleMetaValue with the name of the protocol, e.g. "UDP" or "pbcast.GMS".
• description: SimpleMetaValue with a descrption of the protocol. Probably null for now.
• className: SimpleMetaValue containing the fully-qualified classname of the protocol. Read-only.
• protocolParameters: CompositeValue containing the set of protocol-specific configuration attributes. The set of keys in the composite value is the set of attribute names. Each value is a CompositeMetaValue representing the attribute, with the following structure:
• description: SimpleMetaValue containing a description of the attribute. Null for now, but later releases of JGroups annotate the protocol classes with annotations from which descriptions can be obtained.
• value: SimpleMetaValue with the value of the attribute; value is a String.

Note that for now only the actually configured attributes will be exposed; i.e. attributes relying on defaults will not be exposed. New attributes can be added to override the defaults, as long as they are valid for the protocol.

Note that an earlier draft of this page had protocolParameters as a CollectionMetaValue, with a name property added to the CompositeValue for each attribute. I changed this to a map structure with the name as a key.

MetaValue Representation of a JGroups View

A JGroups View is represented as a CompositeMetaType with the following structure:

• id: SimpleMetaValue with the sequence number of the view, which is of type long.
• creator: SimpleMetaValue with the String representation of the JGroups Address of the cluster node that created the view.
• members: CollectionMetaValue whose elements are each a SimpleMetaValue with the String representation of the JGroups Address of a member of the group.
• coordinator: SimpleMetaValue with the String representation of the JGroups Address of the cluster node that is the coordinator.

Note that an earlier draft of this page had a payload attribute. That was removed as 1) it's not a single value, but rather a map and 2) it's not currently used.