Index Changes

JMX Notifications

This feature requirement comes from product teams who want to match the monitoring and management capabilities of Java CAPS 5.x products. Users need to be able to monitor the state of the JBI runtime and of entities installed and deployed therein. Implementation of this feature requires:

  • A framework for generation of JMX notifications for events that occur in the JBI runtime
  • Instrumentation in the JBI runtime to generate the JMX notifications at the appropriate points
  • A single MBean that can consolidate the notifications from all instances within a single domain and provide those to any client that registers as a notification listener
The events that are the target of this mechanism are any events which change the effective state of the JBI runtime. Notification clients should be able to register with the JBI Runtime and monitor events which occur in the JBI runtime and affect the states of Components (Binding Components and Service Engines), Shared Libraries, Service Units, Service Assemblies, and the JBI runtime itself. Notifications will be emitted whenever one of these entities undergoes an operation which changes its state or adds or removes it from the system. The following list contains the required notifications:
  • Service Assembly:
    • Deployed
    • Started
    • Stopped
    • Shut down
    • Undeployed
  • Service Unit:
    • Deployed
    • Started
    • Stopped
    • Shut down
    • Undeployed

These notifications are not required but will be included:

  • JBI Runtime:
    • Ready
    • Started
    • Stopped
  • Component (Binding Component / Service Engine):
    • Installed
    • Started
    • Stopped
    • Shut down
    • Uninstalled
  • Shared Library:
    • Installed
    • Uninstalled

These notifications are optional and may be included if time permits:

  • Service Assembly:
    • Starting
    • Stopping
    • Shutting down
  • Service Unit:
    • Starting
    • Stopping
    • Shutting down
  • Component:
    • Starting
    • Stopping
    • Shutting down

Generic Requirements

Notifications take the form of a javax.management.Notification object, and include following information:

  • type - a dotted string describing the notification, such as "com.sun.jbi.started.binding.component"
  • msg - the message resulting from the operation, such as "Binding sun-http-binding started successfully"
  • userData - A javax.management.openmbean.CompositeData object which contains the following:
    • Event type: Deployed, Undeployed, Installed, Uninstalled, Started, Stopped, ShutDown
    • Source type: BindingComponent, ServiceEngine, SharedLibrary, ServiceAssembly, ServiceUnit, JBIRuntime
    • Source name: component name, shared library name, service assembly name, or service unit name
    • Target name: server, instance, or cluster+instance name, obtained from PlatformContext
    • Component name: this is present only for Service Unit notifications
    • Service Assembly name: this is present only for Service Unit notifications

Note: There will be no notification for failed operations; only successful operations will emit notifications.

Any clients which register as notification listeners can implement javax.management.NotificationFilter to filter out the notifications in which they are not interested. A client will register with one DAS Event Notifier MBean which will in turn forward notifications from all instances in the domain. The DAS Event Notifier MBean will register with each instance's Event Notifier MBean as a notification listener. The DAS Event Notifier MBean will register with the MBean Server in the facade Management Runtime Service.

Use Cases

These are the use cases that provide the functional view of what this project provides. These use cases will be broken down into lower-level use cases in the detailed design for each functional area. The intent is that these use cases provide enough information for the QE and doc teams to plan for what new functionality needs to be tested and documented.

Use Case Name
Notify01
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
ComponentFramework - JBI runtime service that controls component operations.
Basic Flow: User Action
Admin Client installs or uninstalls a Shared Library or a Component.
Basic Flow: System Action
ComponentFramework performs the installation or uninstallation and upon completion, calls the instance Event Notifier MBean to generate a notification of the install or uninstall event for the Shared Library or Component. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify02
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
ComponentFramework - JBI runtime service that controls component operations.
Basic Flow: User Action
Admin Client starts, stops, or shuts down a Component.
Basic Flow: System Action
ComponentFramework performs the life cycle operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the start, stop, or shutdown event for the Component. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify03
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
DeploymentService - JBI runtime service that controls Service Assembly operations.
Basic Flow: User Action
Admin Client deploys or undeploys a Service Assembly.
Basic Flow: System Action
DeploymentService performs the deployment or undeployment operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the deploy or undeploy event for the Service Assembly. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify04
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
DeploymentService - JBI runtime service that controls Service Assembly operations.
Basic Flow: User Action
Admin Client starts, stops, or shuts down a Service Assembly.
Basic Flow: System Action
DeploymentService performs the life cycle operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the start, stop, or shutdown event on the Service Assembly. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify05
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
ServiceUnitFramework - JBI runtime service that controls Service Unit operations.
Basic Flow: User Action
Admin Client deploys or undeploys a Service Assembly.
Basic Flow: System Action
For every Service Unit in the Service Assembly, ServiceUnitFramework performs the deployment or undeployment operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the deploy or undeploy event for the Service Unit. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify06
Date written
11/09/2007
Actors
Admin Client - a client using admin console, asadmin, or asant to administer the system.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
ServiceUnitFramework - JBI runtime service that controls Service Unit operations.
Basic Flow: User Action
Admin Client starts, stops, or shuts down a Service Assembly.
Basic Flow: System Action
For every Service Unit in the Service Assembly, ServiceUnitFramework performs the life cycle operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the start, stop, or shutdown event for the Service Unit. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Use Case Name
Notify07
Date written
11/27/2007
Actors
AppServer - the application server in which the JBI runtime is installed.
Event Notifier MBean – MBean responsible for emitting JBI runtime notifications for each instance.
JBIFramework - JBI runtime life cycle service.
Basic Flow: User Action
AppServer starts or stops the JBIFramework.
Basic Flow: System Action
The JBIFramework performs the life cycle operation and upon completion, calls the instance Event Notifier MBean to generate a notification of the ready, start, or stop event for the JBI runtime. The Event Notifier MBean emits the notification, which is in turn received by the DAS Event Notifier MBean. The DAS Event Notifier MBean then re-emits the notification so that any listening clients can receive the notification.

Design Details

Event Notifier MBean Names

The DAS Event Notifier MBean name is: com.sun.jbi:Target=domain,ServiceName=Framework,ServiceType=Notification

The instance Event Notifier MBean name is: com.sun.jbi:JbiName=instance-name,ServiceName=Framework,ControlType=Notification,ComponentType=System
where instance-name is the name of the instance.

Event Notifier API For JBI Runtime

An MBean interface named EventNotifierMBean will be added to the runtime.base service in the com.sun.jbi.framework package. The implementing class EventNotifier will be added to the runtime.framework service in the com.sun.jbi.framework package.

The com.sun.jbi.framework.EventNotifierMBean interface provides some enumerators for event and source types, along with methods for emitting notifications:
    /**
     * Events that generate notifications.
     */
    enum EventType {
        Installed,
        Upgraded,
        Uninstalled,
        Deployed,
        Undeployed,
        Ready,
        Started,
        Stopped,
        ShutDown
    }

    /**
     * Sources of notifications.
     */
    enum SourceType {
        JBIRuntime,
        BindingComponent,
        ServiceEngine,
        SharedLibrary,
        ServiceUnit,
        ServiceAssembly
    }

    /**
     * This method is called to emit a notification for an event on the JBI
     * runtime. The caller provides information that determines the content of
     * the notification. The event type for a JBI runtime notification can be
     * Ready, Started, or Stopped. The source type is always JBIRuntime.
     *
     * @param eventType the type of event that occurred.
     * @param msg a message associated with the event.
     * @return the actual Notification sent.
     */
    Notification emitRuntimeNotification(EventType eventType, String msg);

    /**
     * This method is called to emit a notification for an event on either a
     * binding component or a service engine. The caller provides information
     * that determines the content of the notification. The event type for a
     * component notification can be Installed, Uninstalled, Started, Stopped,
     * or ShutDown. The source type is either BindingComponent or ServiceEngine.
     *
     * @param eventType the type of event that occurred.
     * @param sourceType the type of component on which the event occurred.
     * @param componentName the name of the component on which the event
     * occurred.
     * @param msg a message associated with the event.
     * @return the actual Notification sent.
     */
    Notification emitComponentNotification(EventType eventType,
        SourceType sourceType, String componentName, String msg);

    /**
     * This method is called to emit a notification for an event on a shared
     * library. The caller provides information that determines the content of
     * the notification. The event type for a shared library notification can be
     * either Installed or Uninstalled. The source type is always SharedLibrary.
     *
     * @param eventType the type of event that occurred.
     * @param sharedLibraryName the name of the shared library on which the
     * event occurred.
     * @param msg a message associated with the event.
     * @return the actual Notification sent.
     */
    Notification emitSharedLibraryNotification(EventType eventType,
        String sharedLibraryName, String msg);

    /**
     * This method is called to emit a notification for an event on a service
     * assembly. The caller provides information that determines the content
     * of the notification. The event type for a service assembly notification
     * can be Deployed, Undeployed, Started, Stopped, or ShutDown. The source
     * type is always ServiceAssembly.
     *
     * @param eventType the type of event that occurred.
     * @param serviceAssemblyName the name of the service assembly on which the
     * event occurred.
     * @param msg a message associated with the event.
     * @return the actual Notification sent.
     */
    Notification emitServiceAssemblyNotification(EventType eventType,
        String serviceAssemblyName, String msg);

    /**
     * This method is called to emit a notification for an event on a service
     * unit. The caller provides information that determines the content of the
     * notification. The event type for a service unit notification can be
     * Deployed, Undeployed, Started, Stopped, or ShutDown. The source type is
     * always ServiceUnit.
     *
     * @param eventType the type of event that occurred.
     * @param serviceUnitName the name of the service unit on which the event
     * occurred.
     * @param serviceAssemblyName the name of the service assembly to which the
     * service unit belongs.
     * @param componentName the name of the component to which the service unit
     * is deployed.
     * @param msg a message associated with the event.
     * @return the actual Notification sent.
     */
    Notification emitServiceUnitNotification(EventType eventType,
        String serviceUnitName, String serviceAssemblyName,
        String componentName, String msg);

The com.sun.jbi.framework.EventNotifier class implements the above interface, and is a subclass of javax.management.NotificationBroadcasterSupport, which provides the basic implementation necessary for emitting notifications. Any code in the runtime that needs to emit notifications can call the methods on this class directly. The com.sun.jbi.framework.EnvironmentContext class provides a method for obtaining a reference to the MBean that any runtime code can call through the com.sun.jbi.EnvironmentContext interface.

One important implementation detail is that all issuing of notifications must be done on separate threads to prevent a notification listener (over which the runtime has no control) from causing performance degradation of the runtime. This is easily achieved using the java.util.concurrent package.

DAS Event Notifier MBean

An MBean interface named RuntimeNotificationMBean will be added to the runtime.esb-manage service in the com.sun.jbi.management.facade package. This interface will be implemented by the RuntimeNotification class in the same package. The RuntimeNotification class also implements javax.management.NotificationListener and com.sun.jbi.platform.PlatformEventListener and is a subclass of javax.management.NotificationBroadcasterSupport. This class registers itself as a notification listener for each com.sun.jbi.framework.EventNotifier MBean in the domain. Implementing the com.sun.jbi.platform.PlatformEventListener interface allows it to be notified whenever an instance is deleted or created, so that it can keep its notification listener registrations updated. This MBean is registered with the DAS MBean Server by the Management Runtime Service.

Notification Points

The following table lists the methods on com.sun.jbi.framework.EventNotifier and which methods call them:
  • emitRuntimeNotification()
    • called by com.sun.jbi.framework.JBIFramework start(), ready(), and shutdown() methods
  • emitComponentNotification()
    • called by com.sun.jbi.framework.ComponentFramework installComponent(), uninstallComponent(), startComponent(), stopComponent(), and shutDownComponent() methods
  • emitSharedLibraryNotification()
    • called by com.sun.jbi.framework.ComponentFramework installSharedLibrary() and uninstallSharedLibrary() methods
  • emitServiceAssemblyNotification()
    • called by com.sun.jbi.management.system.DeploymentService deploy(), undeploy(), start(), stop(), and shutDown() methods
  • emitServiceUnitNotification()
    • called by com.sun.jbi.framework.ServiceUnitFramework startServiceUnit(), stopServiceUnit(), and shutDownServiceUnit() methods
    • called by com.sun.jbi.framework.Deployer deploy() and undeploy() methods

Details on Notification UserData

The CompositeData that is passed in the UserData field of the notifications can have either of two formats. The first format is for all notifications except for those for Service Unit events; the second format is for Service Unit events only. The following fields are present in both formats:
KeyValue
EventType the type of event: "Installed", "Uninstalled", Deployed, Undeployed, Started, Ready, Stopped, or ShutDown
SourceType the type of source of the event: JBIRuntime, BindingComponent, ServiceEngine, SharedLibrary, ServiceAssembly, or ServiceUnit
TargetName the name of the target where the event originated: either "server" or "clustername-instancename"
SourceName the name of the source of the event: "JBIFramework", component name, shared library name, service assembly name, or service unit name

The following fields are present only in the UserData for a Service Unit event:

KeyValue
ServiceAssemblyName the name of the service assembly to which the service unit belongs
ComponentName the name of the component to which the service unit is deployed


JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-45) was last changed on 03-Mar-09 02:26 AM, -0800 by Gopalan Suresh Raj