Developer's Guide

Autonomic Computing Toolkit
Developer's Guide

Document Number SC30-4083-02

Note

Before using this information and the product it supports, read the general information in Appendix C, Notices.

Second Edition (August 2004)

This edition applies to Release 2 of the Autonomic Computing Toolkit and to all subsequent releases and modifications until otherwise indicated in new drafts.

(C) Copyright International Business Machines Corporation 2004. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.


Contents

Tables

Figures

About this guide

  • How to use this guide
  • Who should read this guide
  • Related publications
  • Accessibility
  • Web sites
  • How to send your comments
  • Manageability interface

  • From concept to implementation
  • Sensor and effector operations
  • Interaction styles
  • Interaction styles implementation
  • Two special classes
  • Initializing interactions
  • Exposing the interfaces
  • Translating exposed interfaces into custom actions
  • Autonomic managers

  • A level 2 autonomic manager (managed)
  • A level 3 autonomic manager (predictive)
  • A level 4 autonomic manager (adaptive)
  • Resource model basics
  • Building a resource model
  • Exporting the resource model
  • Examining the resource model
  • Managed resource touchpoints

  • GLA-enabled touchpoints
  • The GLA adapter file
  • The GLA outputter class
  • Solution Installation and Deployment touchpoints
  • Custom touchpoints
  • Sample autonomic solutions

  • A level 2 autonomic solution (managed): the LTA
  • Scenario synopsis
  • Customizing the managed resource touchpoint
  • Customizing the autonomic manager
  • Customizing the interactions
  • Running the solution
  • A level 3 autonomic solution (predictive): Solution Installation and Deployment scenarios
  • Scenario synopsis
  • Customizing the managed resource touchpoint
  • Customizing the autonomic manager
  • Customizing the interactions
  • Running the solution
  • A level 4 autonomic solution (adaptive): The Problem Determination scenario
  • Scenario synopsis
  • Customizing the managed resource touchpoint
  • Customizing the autonomic manager
  • Customizing the interactions
  • Using Integrated Solutions Console to view the solution
  • Running the solution
  • Custom autonomic solutions

  • Creating a custom autonomic solution
  • Assumptions
  • Development setup
  • Solution steps
  • Modifying the AME resource model
  • Appendix A. Understanding Common Base Events Specification V1.0.1

  • Common Base Events and situation data
  • Notational conventions
  • Formatted data and string values
  • Data types
  • String length
  • Case sensitivity
  • Extensibility
  • Versioning
  • CommonBaseEvent description
  • version
  • localInstanceId
  • globalInstanceId
  • creationTime
  • severity
  • priority
  • reporterComponentId
  • sourceComponentId
  • situation
  • contextDataElements
  • msg
  • msgDataElement
  • extensionName
  • extendedDataElements
  • associatedEvents
  • repeatCount
  • elapsedTime
  • sequenceNumber
  • ComponentIdentification description
  • location
  • locationType
  • application
  • executionEnvironment
  • component
  • subComponent
  • componentIdType
  • instanceId
  • processId
  • threadId
  • componentType
  • Situation
  • categoryName
  • situationType
  • reasoningScope
  • ExtendedDataElement description
  • ContextDataElement description
  • AssociatedEvent description
  • associationEngine description
  • MsgDataElement description
  • Common Base Event XML schema
  • Sample Common Base Element XML
  • Common Base Event class hierarchy
  • Common Base Event mappings
  • Component type namespace
  • Appendix B. Getting help, service, and information

    Appendix C. Notices

  • Trademarks
  • Important notes
  • Index


    Tables

    1. Autonomic manager implementations and maturity levels
    2. Autonomic manager/touchpoint combinations in the Autonomic Computing Toolkit
    3. CommonBaseEvent XML properties
    4. ComponentIdentification properties
    5. Situation properties
    6. situationType property
    7. StartSituation properties
    8. StopSituation properties
    9. ConnectSituation properties
    10. RequestSituation properties
    11. ConfigureSituation properties
    12. AvailableSituation properties
    13. ReportSituation properties
    14. CreateSituation properties
    15. DestroySituation properties
    16. FeatureSituation properties
    17. DependencySituation properties
    18. ExtendedDataElement properties
    19. ContextDataElement properties
    20. AssociatedEvent properties
    21. AssociatedEngine properties
    22. MsgDataElement properties
    23. Java 1.4
    24. Apache commons logging
    25. JRAS tracing levels
    26. JRAS logging levels

    Figures

    1. Autonomic computing reference architecture
    2. Interaction styles
    3. Implementation classes
    4. Resource model and interfaces
    5. Log Interactions view
    6. Log View
    7. The CommonBaseEvent schema
    8. Java logo

    About this guide

    The Autonomic Computing Toolkit Developer's Guide is intended as a technical guide to assist programmers in using the technologies included in the Autonomic Computing Toolkit to develop autonomic solutions. This guide provides the foundational techniques that can be combined in many different ways to achieve different solutions addressing a variety of applications.

    The concepts used in this guide build on autonomic computing architectural concepts, and it is recommended that anyone intending to implement autonomic solutions first read the Autonomic Computing Toolkit User's Guide. It offers a solid foundation for comprehending and exploiting the concepts used in this guide.

    After reading this guide, you should be able to combine the technologies in the Autonomic Computing Toolkit with your existing products in order to create useful autonomic solutions.


    How to use this guide

    This guide is a part of a step-wise flow from basic information all the way to creating your own autonomic solutions. The following list summarizes the learning flow:

    1. Read basic autonomic computing information, including the Autonomic Computing Toolkit User's Guide.
    2. Become familiar with the programming concepts by reading this guide. Understand the importance of interaction styles and the interaction style implementation classes presented in Manageability interface. Trace through the code as the concepts are explained.
    3. Understand autonomic managers and managed resource touchpoints by reading Autonomic managers and Managed resource touchpoints, and learning how autonomic managers and resource touchpoints enable sensor and effector interaction styles.
    4. Run the preconfigured solution scenarios. Read Sample autonomic solutions to understand how autonomic managers and managed resource touchpoints combine to form autonomic solutions. Use the Autonomic Computing Toolkit Problem Determination Log/Trace Scenario Guide and the Autonomic Computing Toolkit Solution Installation and Deployment Scenario Guide to install and run the solutions.
    5. Develop your own autonomic solutions. Read Custom autonomic solutions to understand how you can customize the existing technologies in the Autonomic Computing Toolkit to implement customized autonomic solutions.

    There is an appendix that provides detailed reference information for several of the technologies in this guide.


    Who should read this guide

    This guide is for software developers using the Autonomic Computing Toolkit. Expected users of this Autonomic Computing Toolkit are developers who are interested in developing solutions using the content of the Autonomic Computing Toolkit.


    Related publications

    The latest softcopy versions of documentation are available on the autonomic computing developerWorks Web site at:

    www.ibm.com/developerworks/autonomic/

    The autonomic computing library consists of the following documents:


    Accessibility

    The HTML version of this document and other related publications is accessibility-enabled for use with the IBM Home Page Reader.


    Web sites

    For the latest news and tips on general autonomic computing topics, go to the autonomic computing Web site at:

    www.ibm.com/autonomic

    You can also download the Autonomic Computing Toolkit, documentation, and access additional information from the developerWorks Web site at:

    www.ibm.com/developerworks/autonomic/

    Here you will find information about general autonomic computing concepts, an overview of the Autonomic Computing Toolkit, and most importantly, articles, and tutorials that show you how to apply the tools from the Autonomic Computing Toolkit in real-life situations. After you decide which pieces of the Autonomic Computing Toolkit you need, you can easily download the code right from this Web site.


    How to send your comments

    Your feedback is important to help us provide the highest quality information. If you have any comments about this guide, you can submit them on the IBM autonomic computing Web site at:

    www.ibm.com/developerworks/autonomic/


    Manageability interface

    As outlined in the Autonomic Computing Toolkit User's Guide, the autonomic computing reference architecture defines the concept of an autonomic manager communicating with one or more managed resource touchpoints through a manageability interface organized into sensor and effector operations. Figure 1 shows the autonomic computing reference architecture.

    Figure 1. Autonomic computing reference architecture

    This graphic illustrates an autonomic computing reference architecture

    This chapter shows how to use classes provided in the Autonomic Computing Toolkit to implement the manageability interface. It examines how to initialize that communication and how to use the various interaction styles that implement the sensor and effector operations. The topics in this chapter are the key concepts that will allow the autonomic managers and managed resource touchpoints detailed in Autonomic managers and Managed resource touchpoints to combine to form the autonomic solutions examined in Sample autonomic solutions and Custom autonomic solutions.


    From concept to implementation

    Autonomic managers and managed resource touchpoints communicate through sensor and effector operations. To create autonomic solutions, architectural concepts such as sensor and effector operations must ultimately be translated into a set of classes that represent their functionality.

    Sensor and effector operations are organized into interaction styles, which are, in turn, programmatically implemented. In the Autonomic Computing Toolkit, Java(TM) classes are used to implement the interaction styles.


    Sensor and effector operations

    In the simplest terms, sensor operations are typically used to transmit events or properties to an autonomic manager, whereas effector operations are typically used to cause some sort of change in a managed resource, such as altering state data or setting property values.


    Interaction styles

    Sensor and effector operations are organized into a set of interaction styles that formalize and define how an autonomic manager and its managed resources interact. Sensor and effector operations each can have two interaction styles, as illustrated in Figure 2.

    Figure 2. Interaction styles

    Interaction styles

    Typical uses for these interaction styles are:

    These interaction styles are differentiated by whether the autonomic manager or the managed resource makes contact first. In the cases of the sensor receive-notification and the effector call-out-request, the managed resource makes contact first.

    This release of the Autonomic Computing Toolkit deals mainly with the receive-notification style of interaction, in which a managed resource touchpoint asynchronously sends Common Base Events to an autonomic manager. The retrieve-state interaction style is also illustrated in the solution install and deployment technologies-based autonomic solutions.


    Interaction styles implementation

    The Autonomic Computing Toolkit provides implementation classes for the receive-notification interaction style, as well as other interfaces necessary for initiating contact between autonomic managers and their managed resources. The technologies in the Autonomic Computing Toolkit use Java(TM) technology for this purpose, although any programming language could be used.

    These implementation classes are included in a .jar file named amtapi.jar, which can be found in the Problem Determination scenario bundle. To use the classes in an autonomic solution, the amtapi.jar file must be placed in the Java classpath at build time.

    The classes provided in amtapi.jar represent the most contemporary autonomic interaction implementations. For historical reasons, some of the autonomic solution scenarios in the Autonomic Computing Toolkit do not use these classes, although they still do conform to the autonomic reference architecture and use the sensor and effector interaction styles described earlier.

    It is strongly recommended that any new custom solutions you create use these implementation classes.

    Note:
    The classes in amtapi.jar use Java remote method invocation (RMI) for object resolution and binding. The autonomic computing reference architecture does not require RMI as a binding mechanism; other binding methods could be used. For background information on Java RMI, see the documentation included with the Java 2 platform, Standard Edition (J2SE) documentation.

    Two special classes

    To encapsulate the functionality required for interaction style implementation, two special classes are included in amtapi.jar. These classes are com.ibm.autonomic.resource.ManagedResourceTouchpoint and com.ibm.autonomic.manager.AutonomicManagerTouchpointSupport. Their relationship is shown in Figure 3.

    Figure 3. Implementation classes

    Implementation classes

    These two classes are responsible for initializing interactions, exposing the interfaces that support interaction style functionality, and translating the interaction style interface invocations into meaningful actions within an autonomic manager or managed resources. These functions are discussed in more detail in the following sections of this chapter.

    The responsibilities of the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes are as follows:

    The implementations of these classes in the Autonomic Computing Toolkit provide a basic implementation for each of the functions just listed. The Problem Determination scenario included in the Autonomic Computing Toolkit provides PDAutonomicManagerTouchpointSupport and PDManagedResourceTouchpoint classes that extend the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes, respectively.

    For convenience in the following discussion, these two special classes will collectively be referred to as the implementation classes. Source code for these classes is included in the amtapi.jar file and it is recommended that you refer to these for the following discussion.

    Initializing interactions

    Before autonomic managers and managed resource touchpoints can start interacting, the implementation classes must be instantiated. The autonomic manager must then find its managed resources and assign itself as their manager. These operations are described next.

    Class instantiation

    Each of the implementation classes is provided with a Java main method so that they can be instantiated directly (for testing purposes). However, the most common way that these classes will be created by instantiation during autonomic manager startup, in the case of the AutonomicManagerTouchpointSupport class, or during startup of the resources that comprise a managed resource, in the case of the ManagedResourceTouchpoint class.

    The only requirement for creating the implementation classes is that each one's start() method be invoked immediately after instantiation. The start() methods perform, among other duties, housekeeping functions and publication of the classes to the RMI registry.

    Publishing to RMI

    Each of the implementation classes publish themselves in the RMI registry of the machine where they are instantiated. Because Release 1 of the Autonomic Computing Toolkit supports only single-machine autonomic solutions, there is only one host machine and therefore, a single RMI registry. The classes both publish to the RMI registry on localhost. Both classes extend the Java UnicastRemoteObject to facilitate publication in an RMI registry.

    To publish itself to the RMI registry, the ManagedResourceTouchpoint class invokes its publish() method from within its start() method. A portion of the publish() method is shown in the following code sample:

    protected void publish(ManagedResourceTouchpoint res, 
    					String resourceURL) 
    throws RemoteException
    {
    		if (System.getSecurityManager() 
    		== null)
    {
    System.setSecurityManager(new RMISecurityManager
    		());
    }
    try
    {
    	Naming.rebind(resourceURL, res);
    }
                                                                       .
                                                                       .
                                                                       .
     
    

    Notice that the method sets a security manager if one is not present (required by RMI) and then binds the ManagedResourceTouchpoint (passed as an argument) into the RMI registry using the URL string (also passed as an argument). The start() method invokes this method as follows:

    publish(this, "//localhost/ManagedResourceTouchpoint");
    

    Note that the class passes its own instance as the ManagedResourceTouchpoint instance and a fixed URL string as the binding URL. This is the default behavior for the class. It is expected that custom solutions that extend this class will provide their own URL strings.

    The AutonomicManagerTouchpointSupport class uses a similar method to publish itself in the RMI registry.

    Because the autonomic manager must make first contact with its managed resource touchpoints, it is important that the ManagedResourceTouchpoint class be instantiated first so that it will be available in the RMI registry when the AutonomicManagerTouchpointSupport class is created.

    Assigning the autonomic manager

    After the autonomic manager and managed resource touchpoints have been published, the autonomic manager can look up its managed resource touchpoints and assign itself as their manager. To do this, the autonomic manager resolves each associated touchpoint from the RMI registry and then invokes the assignManager() method on each of those touchpoints, specifying itself as the autonomic manager to be assigned. The managed resource touchpoint then uses this supplied address for subsequent invocations of its autonomic manager's interface.

    To accomplish this binding, the autonomic manager must be supplied with a list of the addresses of its managed resource touchpoints. In the Autonomic Computing Toolkit examples, this is accomplished by using constant addresses in the autonomic manager's startup routines, or by retrieving a list of the addresses from a data repository (other methods, such as performing searches within a machine or network, or querying another autonomic manager for a list, could also be used). The autonomic manager then uses the specified addresses to obtain pointers to each managed resource touchpoint.

    A portion of the AutonomicManagerTouchpointSupport class start() method is shown in the following code sample. This part of the method resolves the touchpoints and invokes their assignManager() methods.

                               .
                               .
                               .
    // resolve all resource touchpoints
     
    ManagedResourceTouchpoint resolvedTP = 
         		 resolveTouchpoint
    			("//localhost/ManagedResourceTouchpoint");
        	
    // add resolved touchpoint to touchpoint list
        	
    			resourceTouchpoints.add(resolvedTP);
        	
    // loop and assign self as manager for all resolved touchpoints
        	
    			Iterator i = resourceTouchpoints.iterator();
        	    		while (i.hasNext()	
    					)
    			{
     
    // get the next touchpoint in the list
     
    ManagedResourceTouchpoint mrtp = 
          (ManagedResourceTouchpoint)i.next();
        		
    // assign self as manager
        	 
          mrtp.assignManager(this);
    		}
                               .
                               .
                               .
     
    

    To look up its touchpoints, the method invokes a protected method within the AutonomicManagerTouchpointSupport class that simply performs an RMI naming lookup, using the URL passed as an argument, and returns the corresponding touchpoint instance from the RMI registry. The method then places this resolved touchpoint into a list contained in the AutonomicManagerTouchpointSupport class that tracks the touchpoints that the autonomic manager is responsible for. The method then loops through this list and invokes the assignManager() method of each resolved touchpoint, specifiying itself as the touchpoint's autonomic manager.

    At this point, the implementation classes are now instantiated, published in the RMI registry, and can contact each other to invoke interaction style interfaces. Before the interaction styles can be used, though, the interfaces must be exposed and implemented, as described in the following sections.

    Exposing the interfaces

    In Release 1 of the Autonomic Computing Toolkit, only one interaction style interface is exposed: the sendEvent() interface that is used for the receive-notification interaction style, exposed by the AutonomicManagerTouchpointSupport class.

    The receive-notification sensor interaction style

    The receive-notification interaction style is exposed by autonomic managers. It is used to asynchronously send event data to an autonomic manager for processing. The sendEvent() operation, exposed by an autonomic manager, is used to implement this interaction style, as detailed in the following sections.

    Using Autonomic Manager::sendEvent

    The sendEvent() operation allows a Common Base Event to be asynchronously sent to an autonomic manager for processing. This operation is exposed by an autonomic manager; therefore, a managed resource touchpoint uses its reference to its autonomic manager (set in the assignManager() invocation) to invoke the sendEvent() method. The ManagedResourceTouchpoint class provides a public method, called sendEventToManager(), to allow managed resources to send Common Base Events to their autonomic managers.

    The following example shows code from the ManagedResourceTouchpoint class.

    public boolean 
    sendEventToManager(ICommonBaseEvent cbe) 
    		throws RemoteException
    {
    		if (autoManager != null)
    {
     
    // invoke sendEvent to send the CBE to the autonomic manager
     
    autoManager.sendEvent(cbe);
    		return true;
    }
        	else
      {
        	return false;
    }
      }
     
    

    Notice that the Common Base Event is passed to the method as an ICommonBaseEvent interface object, as defined in the Hyades project (see Working with Common Base Events) and that the touchpoint invokes the sendEvent() method with a variable that contains a reference to its autonomic manager. This reference was set when the touchpoint's assignManager() method was invoked.

    The default implementation of the sendEvent() method in the AutonomicManagerTouchpointSupport class returns a message that indicates that the method is not implemented. Custom implementations of this class might override the behavior of sendEvent() method to provide the correct behavior for this method. See A level 4 autonomic solution (adaptive): The Problem Determination scenario for an example.

    Working with Common Base Events

    The sendEvent() method uses a Common Base Event to send event information to an autonomic manager. There are two ways to generate Common Base Events using component provided in the Autonomic Computing Toolkit. The first method is to use the GLA to translate existing log file events into Common Base Events (see GLA-enabled touchpoints). The second method is to directly create Common Base Events using the classes included in the hlevents.jar file as described in Custom touchpoints.

    Detailed description of Common Base Events can be found in Appendix A, Understanding Common Base Events Specification V1.0.1.

    Translating exposed interfaces into custom actions

    Custom autonomic solutions can extend the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes and provide their own implementations of the class methods. This is especially true for the interfaces that implement interaction styles.

    Interaction style interfaces must be customized so that the methods translate the required autonomic functionality into the actions that must be performed on an underlying system for the required behavior to occur. For example, the default behavior of the sendEvent() method, used for the receive-notification interaction style, is to return a message indicating that the method is unimplemented. In order for this method to be handled properly in a custom implementation, this method must be overridden and updated to include actions that are meaningful to the autonomic manager for that implementation, such as updating the method to allow the autonomic manager to consume the Common Base Event.

    See A level 4 autonomic solution (adaptive): The Problem Determination scenario for an example of this customization.


    Autonomic managers

    The Autonomic Computing Toolkit contains several sample implementations of the autonomic manager architecture concept. These autonomic manager implementations are intended to assist the developer in understanding the functions of an autonomic manager and demonstrate their use as part of an autonomic solution.

    The autonomic manager implementations included in the Autonomic Computing Toolkit demonstrate how varying levels of autonomic maturity can be achieved. Table 1 shows the autonomic maturity levels for autonomic manager implementations included in the Autonomic Computing Toolkit. See the Autonomic Computing Toolkit User's Guide for a description of autonomic maturity levels.

    Table 1. Autonomic manager implementations and maturity levels

    Level 2 (managed) Level 3 (predictive) Level 4 (adaptive)
    Log and Trace Analyzer tool Solution install and deployment technologies Autonomic Management Engine
    Note:
    Level 1 (Basic) and Level 5 (Autonomic) don't apply to the level of autonomy with which we are concerned.

    A level 2 autonomic manager (managed)

    Level 2 autonomic managers enable autonomic solutions that collect information from disparate systems and display that information on a common console. IT staff can then manually take any necessary corrective action.

    The Log and Trace Analyzer (LTA) tool, included in the Generic Log Adapter and Log and Trace bundle of the Autonomic Computing Toolkit, is an example of a level 2 autonomic manager. The LTA is an Eclipse-based tool that enables viewing, analysis, and correlation of log files generated by different products.

    The LTA acts as an autonomic manager when configured to receive Common Base Events. It performs the monitor and analyze parts of the control loop. A managed resource touchpoint passes Common Base Events to the LTA, allowing the autonomic manager to monitor, analyze, and correlate this data, in some cases in real time. Real-time monitoring of situations occurring in the IT environment and analysis of those situations in real-time allows possible courses of action and problem resolutions to be generated and for IT personnel to execute them more quickly.

    In this example, the autonomic manager and the touchpoint use a single interaction style, namely receive-notification. Common Base Events flow asynchronously from the touchpoint to the autonomic manager.


    A level 3 autonomic manager (predictive)

    Level 3 autonomic managers add predictive aspects to an autonomic solution. A level 3 autonomic manager can make use of the analysis of available knowledge and recommend appropriate actions to administrators.

    The Solution Installation and Deployment dependency checker and change manager, demonstrated in the Autonomic Computing Toolkit, are examples of a level 3 autonomic manager. The dependency checker acts as an autonomic manager, managing the solution installation process. During this process, the dependency checker looks ahead to determine whether or not dependencies, such as prerequisites and corequisites, are met prior to installing the software. The change manager knows how to deploy the software to a given target set (defined via touchpoints) coordinating the change management operations across hosting environment. This predictive aspect of this autonomic manager allows appropriate actions to be taken by IT personnel when dependencies are not met and increases the likelihood of a successful installation.

    The Solution Installation and Deployment dependency checker and change manager interact with Solution Installation and Deployment touchpoints and run time to manage the software installation process and can use the interaction styles described earlier.


    A level 4 autonomic manager (adaptive)

    A level 4 autonomic manager is able to receive event data from a managed resource, correlate that data, decide on an appropriate corrective action, and instruct the managed resource to perform that action.

    The Autonomic Management Engine provides level 4 autonomic manager functionality in the Autonomic Computing Toolkit. The key to understanding how AME functions as an autonomic manager is to understand the concept of a resource model.

    For general information on resource model contents and creation, and for general information about AME, see the Autonomic Management Engine Developer's Guide included in the Autonomic Management Engine bundle of the Autonomic Computing Toolkit.

    Resource model basics

    AME uses the receive-notification interaction style to consume Common Base Events. In programming terms, this means that AME has been provided with a sendEvent() interface (which can be invoked from a managed resource touchpoint) and that it has been modified to consume the Common Base Events that are passed in through this interface. The component within AME that is responsible for monitoring for incoming Common Base Events is called a resource model. Figure 4 shows a block diagram of a resource model and its interfaces.

    Figure 4. Resource model and interfaces

    Resource model and interfaces

    As shown in Figure 4, the Common Base Events sent to the sendEvent() interface are actually placed in a data repository until they are consumed by the monitoring activities of AME.

    Resource models actually consist of a bundle of objects that are used to describe the object being monitored, make decisions about its state, and perform actions based on event input. Resource model bundles are generated when they are exported from the Resource Model Builder (RMB), the tool used to build resource models. RMB is included in the Autonomic Computing Toolkit.

    AME uses an information model standard called CIM-M12 to model resources to be monitored. Common Information Model (CIM) classes, represented by Model Object Format (MOF) files, define the format of data objects that are to be monitored. M12 Java providers invoke classes that assist in translating monitored objects into CIM classes.

    When AME is running, it periodically checks its defined data sources for the presence of objects described by its defined MOF files. If any are found, AME uses the definitions in the MOF file to create instances of the CIM classes described by the MOF file. These instances are then passed to a special JavaScript(TM) function called VisitTree. Within this function, the CIM class instances can be parsed and used to determine information about a monitored system. If required, script files can then be invoked to perform corrective action on a managed system.

    Building a resource model

    The CanonicalSituationMonitor resource model contains elements that allow AME to consume Common Base Events and act upon their contents. Two important objects in the CanonicalSituationMonitor resource model and the functions they provide are:

    Each of these objects are described in more detail in the following sections. You can follow along by examining the resource model in RMB as described in Resource model basics.

    CSF class

    The CSF class is accessed through the CIM Classes tab of the resource model. This CIM class definition tells AME where to look for Common Base Event instances and how to translate them to CSF class instances.

    In the Class properties section of the CSF class, the Common Base Event is defined to be stored in three variables: an integer offset, a file name string, and a situation string. The integer offset defines a separation between each Common Base Event, the file name string defines a common header, and the situation string contains the remainder of the Common Base Event. Hence, all properties of a Common Base Event can be accessed by obtaining and parsing the situation string portion of a CSF class instance that represents a Common Base Event. More than one Common Base Event can exist in the data repository and a separate CSF class instance will be created for each one.

    JavaScript decision algorithm

    After the Common Base Events have been converted to CSF class instances, these instances are passed to VisitTree, the special JavaScript decision function described previously. To see this function, select the Source tab of the resource model and scroll down until you see the VisitTree function.

    A special variable, SVC, is passed to VisitTree. It is essentially an array of the CIM class instances that have been detected in this monitoring cycle. In this case, these will all be CSF class instances representing Common Base Events.

    The VisitTree function first determines how many instances of the CSF class are stored in the SVC array. It then enters a loop to process each instance. Within this loop, the situation string is obtained from the CSF class (representing the situation information of a Common Base Event) and then other local functions are used to extract the Common Base Event parameters. The rest of the loop contains the logic to examine these parameters and respond to their contents by invoking actions through the SVC.ShellCmd function call that drives corrective actions down to the managed resource.

    Exporting the resource model

    Finally, the export facility of the RMB is invoked to generate the CanonicalSituationMonitor resource model bundle. This resource model is now ready for deployment on an AME system. See the AME 1.0 Developer's Guide, included in the Autonomic Management Engine bundle of the Autonomic Computing Toolkit, for information on deploying resource models on an AME system.

    Examining the resource model

    This guide details the resource model that has been created to allow AME to consume Common Base Events, the CanonicalSituationMonitor resource model. This resource model is in the Problem Determination scenario bundle. You can examine it using the RMB as follows:

    1. Find the CanonicalSituationMonitor.zip file in the main directory of the installed Problem Determination scenario bundle.
    2. Unzip this file to a convenient working directory.
    3. Start the RMB from the Start menu.
    4. Select Import from the File menu of the RMB.
    5. Select Existing Project into Workspace.
    6. Browse to the directory where you unzipped the CanonicalSituationMonitor.zip file. This directory will contain a Ca
    7. nonical subdirectory. In that subdirectory, find a .project file and select this file to import.
    8. After the RMB finishes importing, you will see a project named Canonical that contains a Canonical.jrm file. This is the CanonicalSituationMonitor resource model definition file.
    9. Double-click the Canonical.jrm file and it will open in the RMB. Notice that you can navigate to different aspects of the resource model using the tabs along the bottom edge of the editor.

    Managed resource touchpoints

    Managed resource touchpoints represent the interface of a managed resource that can be invoked by an autonomic manager to perform sensor and effector operations. The Autonomic Computing Toolkit contains several sample managed resource touchpoint implementations. Unlike autonomic managers, managed resource touchpoints are not classified according to the autonomic maturity level they enable, because the maturity level of an autonomic solution is really determined by the actions of the autonomic manager. In all maturity levels, managed resource touchpoints perform essentially the same functions: they use the sensor and effector interaction styles to send information to, and receive information and commands from, an autonomic manager. In fact, one of the touchpoint implementations listed in the following sections, GLA-enabled touchpoints, is used with two different autonomic managers to implement autonomic solutions of two different maturity levels: a level 2 solution with the LTA and a level 4 solution with AME.

    The managed resource touchpoint implementations provided in the Autonomic Computing Toolkit are as follows:


    GLA-enabled touchpoints

    The GLA converts existing log messages of several formats to the Common Base Events format that can be consumed by various autonomic manager implementations.

    A fully implemented GLA-enabled touchpoint consists of three parts:

    These parts are described in more detail in the following sections.

    The GLA adapter file

    A GLA adapter file is created using the Adapter Rule Editor tool, which is included in the Autonomic Computing Toolkit. The Adapter Rule Editor is an Eclipse-based tool that provides a development environment that allows you to specify which log file entries to translate to Common Base Events as well as how to perform the transformation. The Adapter Rule Editor also allows you to specify a Common Base Event output handler in the form of a GLA outputter, described in the following sections.

    The output of the Adapter Rule Editor is a GLA adapter file that guides the transformation of log entries to Common Base Events and specifies how to handle them.

    The GLA outputter class

    A GLA outputter class is invoked by the GLA run time when a Common Base Event has been generated from log file entries. This class must extend the org.eclipse.hyades.logging.adapter.impl.ProcessUnit class and must implement the org.eclipse.hyades.logging.adapter.IOutputter interface. This ensures that the methods necessary to handle Common Base Events are available for the GLA to invoke.

    The method that receives the converted Common Base Events is called processEventItems() and it receives an array of Java objects, each object being a Common Base Event object. The Common Base Event objects are instances of the ICommonBaseEvent class from Hyades. The Common Base Event array is then passed to a custom handler within the outputter class for further processing.

    An example of a custom outputter is the ReceiveNotificationOutputter class found in the Problem Determination scenario (see A custom outputter).


    Solution Installation and Deployment touchpoints

    Because Solution Installation and Deployment technologies deal with installing software packages, touchpoints are associated with hosting environments. The Autonomic Computing Toolkit demonstrates operating system Solution Installation and Deployment touchpoints.

    Operating system Solution Installation and Deployment touchpoints implement Solution Installation and Deployment technology-specific sensor and effector interfaces. These touchpoints provide a mechanism for obtaining machine-specific information, such as installed software and current hardware configuration. The operating system touchpoint is intended for use by the Solution Installation and Deployment dependency checker autonomic manager.


    Custom touchpoints

    In addition to the example managed resource touchpoints introduced in previous sections, you can also create custom touchpoint implementations. Although these touchpoints can be created using completely new code, the most convenient way to implement them is by using the manageability interface implementation through extension of the ManagedResourceTouchpoint class. Using this class as a parent for a touchpoint implementation provides the touchpoint class with default behaviors required for managed resource touchpoints. These behaviors are:

    You can then override any methods that require custom implementations to conform to the managed resource environment.

    An example of developing a custom managed resource touchpoint can be found in Creating the managed resource touchpoint class.


    Sample autonomic solutions

    Autonomic solutions combine an autonomic manager implementation with one or more managed resource touchpoint implementations to achieve desired behaviors in a system. The autonomic managers and managed resource touchpoints included in the Autonomic Computing Toolkit work together in different combinations as outlined in Table 2. The autonomic managers are listed in the top row and the managed resource touchpoints are listed in the first column.

    Table 2. Autonomic manager/touchpoint combinations in the Autonomic Computing Toolkit

    Autonomic manager touchpoint LTA Solution Installation and Deployment dependency checker AME
    GLA Level 2 (managed) -- Level 4 (adaptive)
    Solution Installation and Deployment touchpoints -- Level 3 (predictive) --

    The maturity level of the overall solution is determined by the capabilities of the autonomic manager that manages the solution. Some managed resource touchpoints, such as the GLA, can be used in multiple solutions.

    The autonomic managers interact with their managed resource touchpoints using the sensor and effector interaction styles of the autonomic computing architecture, described earlier. Also, you can use certain tools to customize the behaviors of autonomic managers or managed resource touchpoints. The autonomic solutions presented in this chapter, labeled by their autonomic maturity level, list these interaction styles and customization tools for each solution.

    With the exception of the LTA scenario, all of the autonomic solutions presented in this chapter already exist in the Autonomic Computing Toolkit as scenario bundles (see the Autonomic Computing Toolkit User's Guide for a description of these bundles). The customization sections within each solution explain the modifications that have already been performed for each solution, so you do not have to perform all of these steps to run the solution. For information on customizing the Autonomic Computing Toolkit technologies to create custom autonomic solutions, see Custom autonomic solutions.


    A level 2 autonomic solution (managed): the LTA

    This section describes the LTA.

    Scenario synopsis

    A level 2 autonomic solution is demonstrated using the LTA acting as an autonomic manager in combination with the GLA acting as an enabler for a managed resource touchpoint. The LTA consumes log file information that the GLA has transformed into the Common Base Event data format for consistent analysis.

    Customizing the managed resource touchpoint

    Note:

    To customize a touchpoint to interact with the LTA, an adapter file must first be created. The CBELogOutputter included in the GLA provides the capability of passing Common Base Events to the autonomic manager using the following steps:

    1. Create a new Generic log adapter file.
    2. Under the Configuration, make sure you are using a CBELogOutputter.
    3. Under the Context Basic Context Implementation, make sure you create an outputter component using the org.eclipse.hyades.logging.adapter.outputters.CBELogOutputter Executable class and have the UniqueID pointing to the CBELogOutputter ID under the Configuration.
    4. Under the Context Instance, make sure you select the Continuous Operation check box to have your adapter enabled to monitor any new entries in your log file as they are created.
    5. Download A guide for enabling a generic log adapter rule for the Log and Trace Analyzer, available at the following Web site under Documents:

      http://eclipse.org/hyades

    Customizing the autonomic manager

    The LTA interacts with the touchpoint to provide problem determination capabilities. It monitors multiple heterogeneous product log files to isolate application problems occurring in a system.

    The LTA must be configured to receive Common Base Events from the touchpoint. This is accomplished by identifying the machines and CBELogOutputter agent names you want to monitor, then attaching the LTA to the running GLA process.

    To attach to a running GLA, perform the following steps:

    1. Start the LTA.
    2. Go to the Profiling and Logging perspective.
    3. Select Profile -> Attach -> Java process.
    4. On the Attach to Java Process dialog box, expand the process and select the one with your corresponding CBELogOutputter Agent Name.
    5. Select Profile -> Start Monitoring to start collecting events from the GLA instance.
    6. Repeat steps 3 through 5 to attach to all of your different GLA instances.

    You can also create your own symptom database to be used by the analysis engine provided with the LTA. See the online help of the LTA for details on how to create a symptom database.

    For more information on GLA rules,, download A guide for enabling a generic log adapter rule for the Log and Trace Analyzer, available at the following Web site under Documents:

    http://eclipse.org/hyades

    Customizing the interactions

    The LTA allows you to customize your autonomic manager functionality by letting you create your own analysis and correlation engine. Under the Eclipse framework, you can create your own analysis engine and correlation engine plug-ins.

    Running the solution

    By monitoring the different log files generated by the GLA, the LTA provides a managed level of autonomic maturity to your environment.

    1. You can view the captured events in the Log Navigator view. You can correlate logs by right-clicking any log file and selecting New -> Log Correlation. A wizard displays.
    2. Select Log Correlation and click Next.
    3. Add any log files you want to correlate and analyze under the Selected Logs, specify your correlation name, and click Next.
    4. Select your correlation engine in the Correlation schemas list and click Finish. A new correlation will be created under the Correlations folder in the Log Navigator view.
    5. Select your correlation name under the Correlations folder and right-click it.
    6. To view the Log View to analyze the data with the symptom database, select Open With -> Log View.
    7. To view the Log Interactions view (correlation) as shown inFigure 5, select Open With -> Log Interactions .

      Figure 5. Log Interactions view

      Log Interactions view

    8. If you are in the Log View and you want to analyze the data using the symptom databases configured in the LTA, select a record in the Log View, right-click it, and select Analyze All -> Default Log Analyzer or the name of an analysis engine as shown in Figure 6.

      Figure 6. Log View

      Log View ISL UPDATE SCREENSHOT

    For more details, select Help -> Help Contents -> Log and Trace Analyzer.


    A level 3 autonomic solution (predictive): Solution Installation and Deployment scenarios

    This section describes the Solution Installation and Deployment scenarios.

    Scenario synopsis

    To create this level 3 autonomic solution, the Solution Installation and Deployment dependency checker, acting as the autonomic manager, can be used with its touchpoints and run time provided in the Autonomic Computing Toolkit. Two variants of the same scenario that illustrate such a level 3 autonomic solution--each using a different installer (InstallShield for IBM Solution [ISSI] or InstallAnywhere by Zero G) --are detailed in separate documentation provided with the Autonomic Computing Toolkit. In this release, these two scenarios have been combined with a third scenario into a new book that is titled Solution Installation and Deployment Scenario Guide.

    Customizing the managed resource touchpoint

    A Solution Installation and Deployment touchpoint is used in conjunction with the hosting environment in which the software will be installed. The Autonomic Computing Toolkit demonstrates operating system Solution Installation and Deployment touchpoints. The touchpoint must itself be installed, configured, and registered.

    Customizing the autonomic manager

    The Solution Installation and Deployment dependency checker and change manager interact with the solution module and the Solution Installation and Deployment touchpoints and run time to manage the software installation process. It evaluates checks and dependencies of the software that is to be installed as well as dependencies of currently installed software that might be affected by the new installation.

    Customizing the interactions

    The interactions between the Solution Installation and Deployment dependency checker autonomic manager, and the Solution Installation and Deployment touchpoint is driven in large part by the data associated with the installation process, namely the solution modules and solution module descriptors. These data elements defined and describe the software package to be installed, including its structure, installable units, dependencies, checks, and properties. This information is used by the Solution Installation and Deployment autonomic manager to interact with the Solution Installation and Deployment touchpoints.

    To customize the operation of the Solution installation and deployment packaging and installation, an IBM partner solution is required, such as Install Shield’s ISSI or ZeroG’s InstallAnywhere.

    Running the solution

    See the Solution Installation and Deployment Scenario Guide for information about running this solution.


    A level 4 autonomic solution (adaptive): The Problem Determination scenario

    This section describes the Problem Determination scenario.

    Scenario synopsis

    The Problem Determination scenario included in the Autonomic Computing Toolkit represents a level 4 autonomic solution. This scenario combines AME, described in Autonomic managers, with a managed resource touchpoint enabled by the GLA, introduced in Managed resource touchpoints. The resulting autonomic solution is a self-healing system that uses an intelligent control loop to collect system information through Common Base Events, analyze them, plan appropriate responses, and then make necessary adjustments to resolve problems. The managed resource consists of WebSphere(R) Application Server executing a Web application that depends on data from an IBM DB2(R) Cloudscape(TM) database.

    Customizing the managed resource touchpoint

    Two steps are required to customize the GLA touchpoint: defining log entries and defining a custom outputter. These operations are detailed in following sections. A custom adapter file, called PDContextScenario.adapter, contains these changes and can be found in the PDScenario/bin/Adapter subdirectory of the Problem Determination scenario bundle. This adapter file can be opened and examined using the Adapter Rule Editor included with the GLA and LTA bundle.

    Log entry definitions

    To alert the autonomic manager to certain error situations, certain error entries from the WebSphere Application Server and Cloudscape logs must be translated into Common Base Events and sent to the autonomic manager. To accomplish this translation, the Adapter Rule Editor has been used to monitor for and translate the following errors:

    The definitions in the PDContextScenario.adapter file instruct the GLA how to translate these log entries into Common Base Events.

    A custom outputter

    The custom outputter created for this scenario can be found in the mi_api.jar file. Its name is com.ibm.etools.logging.adapter.outputters.ReceiveNotificationOutputter. This class is defined as the outputter class in the PDContextScenario.adapter file. This means that when the GLA wants to output some Common Base Events that it has created, it will invoke this outputter class.

    The ReceiveNotificationOutputter class implements the IOutputter interface of the GLA. This means that it implements a special method called processEventItems(Object[] msgs). The Object array passed to this method is actually an array of Common Base Event objects.

    In the ReceiveNotificationOutputter class, this method invokes a private method that passes each Common Base Event to a customized implementation of the ManagedResourceTouchpoint class (see PDAutonomicManagerTouchpointSupport). The customized ManagedResourceTouchpoint class then invokes the sendEvent() method of its autonomic manager, thus using the receive-notification interaction style to asynchronously pass the Common Base Event. The ReceiveNotificationOutputter class has a reference to this customized class because it created an instance of it in its constructor. This instance of the ManagedResourceTouchpoint class serves as the managed resource touchpoint for the entire autonomic solution.

    Customizing the autonomic manager

    To a certain extent, the autonomic manager implementation for this scenario, AME, is already customized for this solution in that it already has a resource model defined that can consume Common Base Events (see Building a resource model). For this scenario, the decision tree in the resource model must also be modified to examine the Common Base Events that are received and develop and execute corrective actions if a problem is found.

    The CanonicalSituationMonitor resource model described here is contained in the Problem Determination scenario bundle (in PDScenario_Home/bin/RM/subdirectory) and can be examined as described in A level 4 autonomic manager (adaptive).

    The part of the resource model that requires modification is the VisitTree JavaScript method. This function can be found by selecting the Source tab for the CanonicalSituationMonitor resource model and scrolling until you see the start of the VisitTree method. This is the part of the resource model that receives the Common Base Events that have been sent to the Common Base Event data repository used by AME (see Building a resource model).

    This particular scenario is looking for Common Base Events that have the following characteristics:

    The above message IDs indicate the error situation of interest. These are the error messages in the WebSphere Application Server and Cloudscape logs that will be translated by the Generic Log Adapter into Common Base Events and sent to the AME Common Base Event data repository where AME retrieves them.

    The general operation of the VisitTree code is:

    1. Receive one or more Common Base Events, passed in as a list of CSF object
    2. Determine the number of Common Base Event CSF objects and loop, processing each one
    3. Parse the desired information from each Common Base Event, such as source component ID, situation type, and message ID
    4. If the source component ID is WAS, process further
    5. If the Situation Type and Message IDs match the ones of interest (specified earlier), invoke shell commands to restart the Web application and the Cloudscape database, thus addressing the problems reported by the Common Base Events

    Customizing the interactions

    This scenario uses the AutonomicManagerTouchpointSupport and ManagedResourceTouchpoint classes introduced in Manageability interface by extending these classes to inherit and customize the base behavior. The classes created are PDAutonomicManagerTouchpointSupport, which extends AutonomicManagerTouchpointSupport, and PDManagedResourceTouchpoint, which extends ManagedResourceTouchpoint. These child classes provide the necessary customized function to allow the customized AME and GLA-based touchpoint to work together to form the autonomic solution. The source code for the customized classes can be found in the pdmi_api.jar file within the Problem Determination scenario bundle of the Autonomic Computing Toolkit. It is recommended that you refer to these files for the following discussion.

    PDAutonomicManagerTouchpointSupport

    This class overrides the parent class's start() and sendEvent() methods as outlined in the following sections.

    start() method override

    The start() method is overridden to provide customized class instantiation and publication to the RMI registry. The method is reproduced here:

    public void start() throws RemoteException
        {
        	// publish this touchpoint support object
        	publish(this, "//localhost/PDAutonomicManagerTouchpointSupport");
        	
        	// resolve all resource touchpoints
        	ManagedResourceTouchpoint resolvedTP = 
                resolveTouchpoint("//localhost/PDManagedResourceTouchpoint");
        	
        	// add resolved touchpoint to touchpoint list
        	resourceTouchpoints.add(resolvedTP);
        	
        	// assign self as manager for all resolved touchpoints
        	Iterator i = resourceTouchpoints.iterator();
        	
        	while (i.hasNext()
    					)
        		{
        			// get the next touchpoint in the list
        			ManagedResourceTouchpoint mrtp = 
               (ManagedResourceTouchpoint)i.next();
        		
        			// assign self as manager
        			mrtp.assignManager(this);
        		}
       	 }
     
    

    The differences between this method and the overridden method are the URL names used to publish the autonomic manager to the RMI registry and to find the published managed resource touchpoint. In this example, these URL names are fixed, although the start() method could invoke another method to obtain a list of URLs for the managed resource.

    sendEvent() method override

    To provide support for the receive-notification interaction style in AME, the sendEvent() function is overridden. A portion of the overridden method from PDAutonomicManagerTouchpointSupport is reproduced here:

    public void sendEvent(ICommonBaseEvent cbe) throws RemoteException
        {
        	// convert the CBE to a string for writting
    	  String cbeMessage = null;
         if(cbe instanceof IExternalizableToXML){
             cbeMessage = ((IExternalizableToXML)(cbe)).externalizeCanonicalXMLString();
         }
         else{
           cbeMessage = cbe.toString();
         }
                          .
                          .
                          .
                // if necessary, create a file writer for the AME CBE log 
            	if ( fw == null )
    		{
    			fw = new FileWriter(CBE_OUT_FILE, false);
    		} 
                          .
                          .
                          .
                // write the CBE to the log so that AME will find it 
    		if ( fw != null )
    		{
    			fw.write(cbemessage);
    			fw.flush();
                          .
                          .
                          . 
     
    

    This method converts the Common Base Event received from the managed resource touchpoint to a string and writes that string to the Common Base Event data repository that the AME uses as its Common Base Event source (see Building a resource model). Hence, the overridden sendEvent() method ensures that Common Base Events are placed in the proper context for consumption by AME when the receive-notification interaction style is used.

    PDManagedResourceTouchpoint

    This class overrides the parent class's start() method as outlined below.

    start() method override

    The start() method is overridden to provide customized class instantiation and publication to the RMI registry. The method is reproduced here:

    public void start() throws RemoteException
        {
    			// publish this touchpoint in the RMI registry
    			publish(this, "//localhost/PDManagedResourceTouchpoint");
        }
     
    

    This method differs from the parent method in that it publishes a URL to RMI that is meaningful in this scenario. This URL is the name that the autonomic manager touchpoint support class uses to find this touchpoint. No other parent class methods need to be overridden for this scenario.

    Using Integrated Solutions Console to view the solution

    The Integrated Solutions Console provides a way to create a browser-based viewing console for the autonomic solution. Integrated Solutions Console is based on the IBM WebSphere Portal Server, and uses this portal capability to provide views into solutions. These views can be anything that can be displayed in a standard Web browser including HTML, JavaScript, and Java applets. Integrated Solutions Console organizes these views using a dynamic HTML-based navigation tree to allow you to move from view to view within a common, browser-based environment. This enables the consolidation of administration interfaces into one convenient place.

    The Problem Determination scenario uses the Integrated Solutions Console to provide a view into the operations of the solution as well as a convenient way to start and stop the scenario. For information about this solution's use of the Integrated Solutions Console, see the Autonomic Computing Toolkit Problem Determination Log/Trace Scenario Guide, included in the Autonomic Computing Toolkit. For in-depth information on developing Integrated Solutions Console components, see the Integrated Solutions Console Developer Information Center, included in the Integrated Solutions Console bundle.

    Running the solution

    With these customizations in place, the level 4 autonomic solution acts as follows: The GLA translates log entries into Common Base Events and sends them to the AME, using the receive-notification interaction style. It uses the overridden sendEvent() method of the PDAutonomicManagerTouchpointSupport class to send the Common Base Events. Finally, AME uses its CanonicalSituationMonitor resource model to consume the Common Base Events, interpret their contents, and perform corrective actions, thus completing a full autonomic self-healing loop.

    For in-depth information on running this autonomic solution, see the Problem Determination Log/Trace Scenario Guide included in the Documentation bundle of the Autonomic Computing Toolkit. That guide contains the information you need to install and configure the software for this scenario, run the scenario, and interpret the results.


    Custom autonomic solutions

    In addition to the standard solutions that can be developed with the Autonomic Computing Toolkit, custom solutions are also possible. This chapter is a guide to using the technologies included in the Autonomic Computing Toolkit with an existing stand-alone product to create a custom autonomic solution.

    Numerous autonomic solutions can be created using the Autonomic Computing Toolkit technologies. Previous chapters have already described the use of sample autonomic solutions, including the use of tools to customize certain aspects of the solution. It is also possible to use the manageability interface implementations to develop new, custom autonomic managers and managed resource touchpoints.


    Creating a custom autonomic solution

    For this particular custom autonomic solution example, you will combine both of the methods mentioned above (modifying existing solutions and creating new ones). The autonomic manager implementation in this solution is AME, which is included in the Problem Determination scenario and was discussed earlier (see A level 4 autonomic manager (adaptive)). You will create a new custom managed resource touchpoint. This custom touchpoint will use the manageability interface implementation classes (see Manageability interface) to directly create and send Common Base Events to its autonomic manager.

    This solution achieves a level 4 (adaptive) maturity level.

    Assumptions

    The example in this chapter uses a hypothetical application server. The following assumptions are made for this sample:

    Development setup

    To set up a development environment for this solution, install the Problem Determination scenario bundle and then make a copy of its installation directory. This copy will contain AME, which you will customize, and the amtapi.jar and associated files, which you will use.

    The following .jar files must be placed in your Java classpath for build time and run time:

    These files can be found in the amtapi/lib subdirectory of the Problem Determination scenario.

    You will also modify the CanonicalSituationMonitor resource model (see A level 4 autonomic manager (adaptive)). Rename and save this resource model.

    A new Java package will be created for this solution called com.ibm.autonomic.sample.as. You will create all of the Java classes for this solution within subpackages of this package.

    Solution steps

    Perform the following steps to implement this custom autonomic solution:

    1. Choose an autonomic operation for the solution.
    2. Create the managed resource touchpoint implementation class.
    3. Create the autonomic manager touchpoint support class.
    4. Customize an AME resource model to support the chosen operations.
    5. Run the solution.

    These steps are detailed in the following sections.

    Choosing an autonomic operation

    The first step in creating an autonomic solution is to decide what aspect of a system might benefit from autonomic capabilities such as self-configuration, self-healing, self-optimization, and self-protection. This example solution illustrates a self-healing scenario that monitors the state of the application server's applications and attempts to address a problem that affects application execution.

    Creating the managed resource touchpoint class

    The managed resource touchpoint class extends the ManagedResourceTouchpoint management interface implementation class, found in amtapi.jar. This allows the solution class to inherit the desired behaviors of the parent class and enables the addition of custom behavior for this particular solution.

    For this solution, this class is named ASManagedResourceTouchpoint.java is created in its own package, com.ibm.autonomic.sample.as.resource. This is very similar to the technique used for the Problem Determination managed resource touchpoint class, PDManagedResourceTouchpoint.java.

    Declaring the managed resource touchpoint class

    The declaration for the ASManagedResourceTouchpoint.java class is shown below.

    Note:
    The import statements will be explained later.
    package com.ibm.autonomic.sample.as.resource;
     
    import java.rmi.RemoteException;
     
    import org.eclipse.hyades.logging.events.ICommonBaseEvent;
     
    import com.ibm.autonomic.resource.ManagedResourceTouchpoint;
     
    /**
     	* ASManagedResourceTouchpoint 
    	 *
     	*/
    	public class ASManagedResourceTouchpoint extends ResourceProcessControl
     
    

    Publishing the resource touchpoint
    Note:
    The autonomic manager and managed resource in this sample are assumed to be on the same machine. Therefore, assume a single RMI registry and that all RMI publications are made to host name localhost.

    The managed resource touchpoint must be published to the RMI registry on the resource machine so that it can be found and used by an autonomic manager. Because you should publish to a different URL than the one that is specified in the parent class's start() method, override that method as follows:

    public void start() throws RemoteException
    {
         publish(this, "//localhost/ASResourceTouchPoint");
    }
     
    

    To actually publish itself, the ASManagedResourceTouchpoint class invokes the publish method inherited from its parent class and passes a pointer to itself (this) and the URL for this touchpoint in the RMI registry (//localhost/ASResourceTouchPoint).

    Generating Common Base Events

    Earlier sections described how to generate Common Base Events using the GLA to convert existing log file entries to Common Base Events. In this solution, you will generate Common Base Events directly within your managed resource and use the custom touchpoint to send these events to the autonomic manager.

    To generate a Common Base Event when an error condition occurs, the ASManagedResourceTouchpoint class must be integrated with the application server. This is done in two ways. First, the ASManagedResourceTouchpoint class needs to become a part of the application server's code base so that it is instantiated when the application server starts up. Second, the error-reporting facilities of the application server need to be modified to invoke methods in the ASManagedResourceTouchpoint class when errors occur so that the touchpoint knows to use the error information to generate the Common Base Event and send it to the autonomic manager.

    For this example, assume that the application server has an error handler that gets invoked when applications are slowing down due to lack of database connections. This handler must be modified to invoke a method in the ASManagedResourceTouchpoint class that will generate a Common Base Event to represent the error condition. The code for this method in the ASManagedResourceTouchpoint class is as follows:

    public void reportDBPoolProblemAsCBE()
     
    	{
        // a db pool problem has occurred...we must generate a Common Base Event
        // representing this problem and send it to the autonomic manager
     
        	try
        	{
            // instantiate an instance of the Common Base Event factory
            ISimpleEventFactory sefi = SimpleEventFactoryImpl.getInstance();
     
            // create the Common Base Event
            ICommonBaseEvent cbe = sefi.createCommonBaseEvent();
     
            // set the creation time
            cbe.setCreationTime(System.currentTimeMillis());
     
            // set the Common Base Event version to 1.0.1
            cbe.setPreferredVersion(ICommonBaseEvent.VERSION_1_0_1);
     
            // set the properties required for a situation 3-tuple; i.e. the component reporting the
            // situation, the component affected by the situation, and the situation itself
     
            // set the source component; i.e. the affected component...this is the application server...
            // by setting this and not the reporting component, the Common Base Event will assume
            // that this is also the reporting component
     
            // create a new instance of a Source Component:
            IComponentIdentification sourceComponentId = sefi.createComponentIdentification();
     
            sourceComponentId.setLocation("127.0.0.1");
            sourceComponentId.setLocationType("IPV4");
            sourceComponentId.setComponent("Example Application Server");
            sourceComponentId.setSubComponent("Application Server DB Connection Pool");
            sourceComponentId.setComponentIdType("Application");
            sourceComponentId.setComponentType("Application Server");
     
            // now set the source component in the Common Base Event
            cbe.setSourceComponentId(sourceComponentId);
     
            // set the situation...because we're dealing with a problem with the db connection pool size,
            // we'll categorize this as a connection situation...first create a new instance of a connection
            // situation
     
            IConnectSituation connSituation = sefi.createConnectSituation();
            connSituation.setSuccessDisposition("UNSUCCESSFUL");
            connSituation.setSituationDisposition("AVAILABLE");
     
            // create a new instance of a situation
            ISituation situation = sefi.createSituation();
            situation.setCategoryName("ConnectSituation");
            situation.setSituationType(connSituation);
     
            // set the situation in the Common Base Event
            cbe.setSituation(situation);
     
            // set the error message id...this is what we're looking for in the Resource Model in order
            // to invoke a corrective action (see section 6.1.7)...the message id is set using a message
            // data element
            IMsgDataElement mde = sefi.createMsgDataElement();
     
            // set the message id and message id type
            mde.setMsgId("AS005E");
            mde.setMsgIdType("AppServer");
     
            // add the message data element to the cbe
            cbe.setMsgDataElement(mde);
     
              // invoke the touchpoint's method that sends a Common Base Event to the autonomic
              // manager using the sendEvent() method...this uses the receive-notification interaction
         	    // style
           	 sendEventToManager(cbe);
     
    		}
        catch (Throwable  th)
        				{
           	 // problem creating the Common Base Event
                                                                                                                                                                                                                                                	 System.out.println("Could not create Common Base Event: " + th);
      	   }
    }
     
    

    The last method invoked is sendEventToManager(). This is actually invoking the parent method, which sends the Common Base Event to the touchpoint's autonomic manager using the sendEvent() method of the manageability interface, thus using the receive-notification interaction style to asynchronously send event data.

    The Common Base Event is being created and sent directly rather than using the GLA to translate log entries. While the GLA is very convenient for generating Common Base Events for existing log files, there is some degradation of performance by using this method and the direct generation method demonstrated here is the preferred method of event generation.

    For in-depth information on the Common Base Event objects and properties used in the method above, see Appendix A, Understanding Common Base Events Specification V1.0.1.

    Creating the manager touchpoint support class

    The manager touchpoint support class extends the AutonomicManagerTouchpointSupport management interface implementation class, found in amtapi.jar.

    For this solution, this class is named ASAutonomicManagerTouchpointSupport.java and is create in its own package, com.ibm.autonomic.sample.as.manager. A very similar technique is used for the Problem Determination manager touchpoint support class, PDAutonomicManagerTouchpointSupport.java.

    Declaring the manager touchpoint support class

    The declaration for the ASAutonomicManagerTouchpointSupport.java class is shown in the following example:

    Note:
    The import statements will be explained later.
    package com.ibm.autonomic.sample.as.resource;
     
    import java.rmi.RemoteException;
     
    import org.eclipse.hyades.logging.events.ICommonBaseEvent;
    import org.eclipse.hyades.logging.events.IComponentIdentification;
    import org.eclipse.hyades.logging.events.IConnectSituation;
    import org.eclipse.hyades.logging.events.IMsgDataElement;
    import org.eclipse.hyades.logging.events.ISimpleEventFactory;
    import org.eclipse.hyades.logging.events.ISituation;
    import org.eclipse.hyades.logging.events.SimpleEventFactoryImpl;
     
    import com.ibm.autonomic.resource.ManagedResourceTouchpoint;
     
    /**
    		 * ASManagedResourceTouchpoint 
    		 *
    																																																																																																																																																																																	 */
    public class ASManagedResourceTouchpoint extends ResourceProcessControl
     
    

    Publishing and connecting to the resource touchpoint

    The manager touchpoint support class instance must be published to the RMI registry so that its managed resource touchpoints that it is managing can address the manager. You should publish the manager touchpoint support class using a different URL than the one specified in the parent class, so override the start() method of the parent class while maintaining its behavior that finds the autonomic manager's managed resource touchpoints and assigns itself as their manager.

    The new start() method in the ASAutonomicManagerTouchpointSupport class is as follows:

    public void start()
        {
            try
            {
                // publish this touchpoint support object
                publish(this, "//localhost/ASAutonomicManagerTouchpointSupport");
     
                // resolve all resource touchpoints
                IManagedResourceTouchpoint resolvedTP = 
                     resolveTouchpoint("//localhost/ASManagedResourceTouchpoint");
     
                // add resolved touchpoint to touchpoint list
                resourceTouchpoints.add(resolvedTP);
     
                // assign self as manager for all resolved touchpoints
                Iterator i = resourceTouchpoints.iterator();
     
                while (i.hasNext())
                {
                    // get the next touchpoint in the list
                    IManagedResourceTouchpoint mrtp = (IManagedResourceTouchpoint)i.next();
     
                    // assign self as manager
                    mrtp.assignManager(this);
                }
     
            }
            catch (Throwable th)
            		{
                System.out.println("Error connecting to managed resources:");
                th.printStackTrace();
            		}
        }
     
    

    The start() method invokes the resolveTouchpoint() method of the parent class, passing the name of the managed resource touchpoint that was published in the start() method of the ASManagedResourceTouchpoint class. The autonomic manager's new start() method also publishes itself to the RMI registry and then assigns itself as the manager of the managed resource touchpoint after the touchpoint is resolved.

    The class manager tracks its managed resource touchpoints using a list that is declared in the parent class. Hence, even though there is only one managed resource in this particular solution, the autonomic manager could manage multiple managed resource touchpoints.

    Assigning the autonomic manager

    When the autonomic manager's start() method resolves a managed resource touchpoint found in the RMI registry, it invokes that touchpoint's assignManager() method, specifying itself as the touchpoint's autonomic manager.

    Adding a main() method to ASAutonomicManagerTouchpointSupport

    Because AME cannot start auxiliary programs during its own startup process, its touchpoint support must be started as a separate process. Hence, in this scenario, the ASAutonomicManagerTouchpointSupport class must be invoked from the command line after AME is started. Therefore, a main() method must be added to the class to instantiate it and invoke its start() method as follows:

    public static void main(String[] args) throws Exception
    {
        // create an instance and start it up
        ASAutonomicManagerTouchpointSupport amts = new 
        ASAutonomicManagerTouchpointSupport();
     
        amts.start();
    }
     
    

    The main() method creates an instance of the ASAutonomicManagerTouchpointSupport class and invokes its start() method, which will cause it to publish itself to the RMI registry.

    Handling the Common Base Event

    In this solution, Common Base Events should be written to a log file where AME can retrieve them. To accomplish this, the sendEvent() method of the ASAutonomicManagerTouchpointSupport class must be overriden. The parent class implementation is just a place holder that throws an exception indicating that the method must be implemented by child classes.

    AME expects to find Common Base Events in a log file called CBEOut.log, so this is where the sendEvent() method writes them, as follows:

    public void sendEvent(ICommonBaseEvent cbe) throws RemoteException
        {
            // convert CBE to string for writing to a file
            String cbeMessage = cbe.toString();
     
            // write the CBE to a the AME datastore file.
            try
            {
                if (fw == null)
                {
                    fw = new FileWriter("CBEOut.log",  false);
                }
            }
            catch (Exception e)
            {
                e.printStackTrace();
                throw new RemoteException("Cannot create CBEOut.log file : " + e.toString());
            }
     
            try
            {
                if (fw != null)
                {
                    fw.write(cbeMessage);
                    fw.flush();
                }
                else
                    System.out.println("CBE out file is null");
     
            }
            catch (Exception e)
            {
                e.printStackTrace();
                throw new RemoteException("Cannot write CBE message : " + e.toString());
            }
        }
     
    

    The method first converts the Common Base Event to a string, because AME expects this format. The method then opens the CBEOut.log file and writes the converted Common Base Event string.

    Modifying the AME resource model

    Because the CanonicalSituationMonitor resource model is already configured to consume Common Base Events, you do not have to modify that aspect of its behavior. The Common Base Events that the modified ASAutonomicManagerTouchpointSupport class writes to the CBEOut.log file can be read by AME and converted to a CSF class instance, which in turn is passed to the VisitTree method, as described in Building a resource model.

    The VisitTree code, however must be modified to look for Common Base Events from your application server, determine whether or not they indicate an error condition, and then initiate any required corrective actions. You also need to modify some of the initialization script to set up some of the variables used by VisitTree. These modifications are outlined in the following sections.

    Variable declarations

    Some variables need to be defined for the VisitTree method as follows:

    // TRACE Constants to be used by Svc.Trace() calls
    var TRACE_ERROR = 0;
    var TRACE_FINE = 2;
    var TRACE_FINER = 3;
    var TRACE_FINEST = 4;
     
    // This variable can be used in your Svc.Trace calls to make it easier to
    // search through the log file and find calls made by your resource models.
     
    var TRACE_SOURCE = "RM TRACE: ";
     
    var str_MY_APPSVR = "MyApplicationServer"; 
     
    //The WAS MSGID which indicates db pool problem
    var str_DB_POOL_ERR = "AS005E";																																																																																									var dbPoolSizeScript = "";
    

    Remove the remaining variable declarations at the beginning of the resource model.

    Initialization

    The init() function must be modified to correctly set variables as follows:

    function Init(Svc)
    {
    	interpType = Svc.GetInterp();
     
    	//Use the interp to set the which file would be executed for recovery
    	if (interpType == "w32-ix86")
    	{
    		dbPoolSizeScript = "IncreaseDBPoolSize.bat";
    	}
    	else
    	{
    		dbPoolSizeScript = "./increasedbpoolsize.sh";
    	}
     
    	Svc.AssociateParameterToClass("parmLogName", "CSF");
     
    	return (0);
    }
     
    

    The script that is invoked to increase the database connection pool size is set based on the operating system platform.

    VisitTree

    Modify the VisitTree method as follows:

    function VisitTree(Svc)
    {
    	var numOfInstances;
    	var idx;
     
    	// Process each situation written to the error log during this cycle.
    	numberOfInstances = Svc.GetNumOfInst("CSF");
     
    	for (idx = 0; idx < numberOfInstances; idx++)
    	{
    		// Note: The entire CBE is bundled up into one property in the CIM
                // class (i.e., situation)...get that property for parsing 
    		var str_situation = Svc.GetStrProperty("CSF", idx, "situation");
     
    		// Extract the properties that are required for the analysis.
    		var str_msgId = getTagValue(str_situation, "<msgId>");
     
    		var str_sourceComponentId_component = getParmValue(str_situation, 
                                                      "component");
     
    		// We are interested only in the situations from our application
                // server
    		if (str_sourceComponentId_component.indexOf(str_MY_APPSVR) > 0)
    		{
    			// If it's the error we're looking for, invoke the db pool
                      // size script to fix the problem
    			if (str_msgId == str_DB_POOL_ERR)
    			{
    			    shellRc = Svc.ShellCmd(startScript);
    	            }
    	 
    		}
    		
    	} 
     
    	return (0);
    }
     
    

    The function first determines how many Common Base Events it has to work with. It then uses a loop to process each one. Within this loop, the situation string of the CSF class is extracted (this represents all of the Common Base Event data; see CSF class). Next, the Common Base Event data of interest is extracted, namely the reporting component and the message ID. If the reporting component matches your application server and the message ID matches the database connection pool size error ID, then the script to correct the problem is invoked. This causes the application server's database connection pool size to be increased, thus completing the self-healing autonomic solution.

    After making the changes to the JavaScript in the resource model, save it and export it using RMB's export facilities.

    Building the sample

    To build the solution, perform the following steps:

    1. Compile the Java classes using either a command line or an integrated development environment such as Eclipse.
      Note:
      The .jar files listed in Development setup must be present in the Java classpath.
    2. Generate the resource model bundle and deploy on the AME system using the export facilities of RMB. This bundle will contain all of the components necessary to define the resource model to an AME system.
    3. Place the resource model into a monitoring profile and then deploy it to an AME endpoint (for information on monitoring profiles and endpoints, see the AME 1.0 Developer's Guide).

    For more information on building a sample, see the AME 1.0 Developer's Guide.

    Running the sample

    To run the sample, the .jar files specified in Building the sample must be in the classpath, along with any .jar files and classes necessary to run AME and the application server. The order in which the various solution components are started is important because the resource touchpoint must be published before the autonomic manager starts. Also, the RMI registry must be started before any touchpoints can be published. Therefore, the start order must be as follows:

    1. Start the RMI registry.
    2. Start the application server. This will in turn instantiate the ASManagedResourceTouchpoint class, which will publish itself in the RMI registry.
    3. Start AME.
    4. Start the ASAutonomicManagerTouchpointSupport class. It will publish itself in the RMI registry and then connect to the published the ASManagedResourceTouchpoint class.

    The running autonomic manager will now monitor incoming Common Base Events that indicate the AS005E error condition and react to them by effecting a corrective action on the application server. To test the solution, you must cause the error condition in the application server. The easiest way to do this is to set the application server database connection pool size to 1, then use a tool to generate a large demand on an application running on the application server that uses database connections. This should cause an overload of the connection pool, thus generating the AS005E error condition and invoking the corrective actions.

    Another possibility is to create a script that artificially generates the error condition within the application server (for example, by invoking the error handler during the application server's post-startup processing). This should in turn generate the Common Base Event indicating the error situation and cause the expected corrective actions.


    Appendix A. Understanding Common Base Events Specification V1.0.1

    This appendix describes the Common Base Event and supporting technologies that define the structure of an event in a consistent and a common format. The purpose of the Common Base Event is to facilitate the effective intercommunication among disparate enterprise components that support logging, management, problem determination, autonomic computing, and e-business functions in an enterprise. This appendix specifies a baseline that encapsulates properties common to a wide variety of events, including business, autonomic, management, tracing, and logging type events. The format of the event is expressed as an XML document using UTF-8 or UTF-16 encoding.

    This appendix is prescriptive about the format and content of the data that is passed or retrieved from a component. However, it is not prescriptive about the ways in which individual applications are to store their data locally. Therefore, the application requirement is only to be able to generate or render events in Common Base Event data format, not necessarily to store them in that format. The goal of this effort is to ensure the accuracy, improve the detail and standardize the format of events to assist in designing robust, manageable and deterministic systems.

    A small event can change things far beyond the seeming initial circumstance. Nowhere is this more true than in today's complex world of e-business where multitudes of interconnected systems must work together to perform many of the simple housekeeping activities that are necessary to keep a computing system healthy. Clearly, in this world, small incidents can have wide-reaching implications and few things are as small, yet pervasive, in a computing infrastructure as an event. The event, which encapsulates message data sent as the result of an occurrence of a situation, represents the very foundation on which these complex systems communicate. Events exchanged between and among applications in complex information technology systems represent the very nervous system that allows these various facets of the system to interoperate, communicate and coordinate their activities. Fundamental aspects of enterprise management and e-business communications, such as performance monitoring, security and reliability, as well as fundamental portions of e-business communications, such as order tracking, are grounded in the viability and fidelity of these events. Quality event data leads to accurate, deterministic and proper management of the enterprise. Poor fidelity can lead to misguided, potentially harmful results, or even results that are fatal to the system. Even simple things such as the formatting of the date and time specified within an event can render the remaining data in the event useless the format used by the sender is not understood by the receiver beforehand. Clearly, efforts to ensure the accuracy, improve the detail and standardize the format of these fundamental enterprise building blocks is an imperative towards designing robust, manageable and deterministic systems. Hence, the Common Base Event is defined as a new standard for events to be used by enterprise management and business applications.

    The Common Base Event described here lends itself easily to several types of events, in particular: logging, tracing, management, and business events. In all of these cases there is a significant need for the data elements and the format of those elements to be consistent, because all of these events need to be correlated with each other. Using log files, or events published to subscribers, most IBM and non-IBM products generate data whose interpretation requires the availability of contextual information. Yet, this context is frequently maintained only in the minds of developers and analysts who are intimately familiar with the application that generates the event. This lack of context can lead to hazardous situations when other applications that are responsible for handling the event attempt to interpret it, or when the event is used for system management or problem determination purposes. Consider again the basic problem of parsing time stamps. Format and granularity (for example, are the units milliseconds or microseconds?) both present needless obfuscation for the application that receives the time-stamped event. A more general problem is the lack of consistency in the information that is presented. For example:

    Obviously, the current lack of standardization creates considerable difficulty for automated situation handling. Complexity increases further when the problem occurs in a solution that is composed of multiple components. Without a standard, data stored in logs or published as events are of little value to autonomic management or business systems that rely on the completeness and accuracy of data to determine an appropriate course of action to take in response to the event. The Common Base Event definition alleviates this problem by ensuring completeness of the data by providing properties to publish the following information:

    All properties defined in the Common Base Event model apply to one of these three broad categories, hereafter referred to as 3-tuple. In addition, the location of the reporter and source components is also considered. The affected component might not reside in the same physical machine as the component that reports it. This broader scope of information encapsulates enough data so that events can be exchanged and interpreted in a deterministic and appropriate manner across multiple management systems that consume the events without losing fidelity due to serial hops among the multiple management systems.


    Common Base Events and situation data

    Table 3 provides a summary of the Common Base Event properties. The entries in the table represent the data that is collected for the 3-tuple. The reporterComponentId and sourceComponentId table entries define the reporter and the affected component IDs respectively. The remaining fields in the table comprise the "situation" data.

    The following sections describe the conventions used in this model.

    Notational conventions

    The key words MUST , MUST NOT, REQUIRED, SHALL. SHALL NOT, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL (shown in uppercase in the following sections) are to be interpreted as they are described in RFC-2119. 1

    Formatted data and string values

    Formatted data is always in human-readable form. All formatted data and string values MUST be encoded as UTF-8 or UTF-16 strings.

    Data types

    The Common Base Event only supports the following subset of XML schema data types and the array variation of these types. Description of these data types can be found in the XML Schema specification. 2 The data types are XML schema signed data types as follows:

    String length

    The maximum string length MUST NOT exceed 1024 characters. If a longer string is needed then a hexBinary type MAY be used.

    Based on empirical data concerning known consumers and constraints placed on the processing and storage of events, field lengths have been specified to ensure the broadest possible acceptance and fidelity. However, it is possible that at times a sender may exceed these length restrictions. In this case, it is incumbent upon the consumer of an event to take appropriate actions to either accept the event as-is, massage it to conform to the specification, or discard as invalid. However, in general, preservation of data -- even data that is out of conformance with this event specification -- is preferable to a total loss of the event. Therefore, it is recommended that all efforts be made to preserve as much of the event data as possible.

    Case sensitivity

    All names and strings specified in this document are case sensitive.


    Extensibility

    The Common Base Event data model described here is built with some level of extensibility to lend itself easily to the needs of a variety of types of events generated by different IT and business products. In particular, the data elements and the format of those elements need to be consistent, as all of these events need to be correlated with each other, but they also need to be flexible to allow for adaptation to product-specific requirements.

    The use of the ExtendedDataElement (described in ExtendedDataElement description) is RECOMMENDED for including product-specific attributes. This property allows for user-supplied extensions for any other attributes not defined in the CommonBaseEvent.

    Product-specific schema MAY be included in the CommonBaseEvent XML Schema (described in Common Base Event XML schema) to extend that property with the product specific requirements in the "any namespace" of the schema. The event consumers or management tools that support the CommonBaseEvent schema SHOULD store and forward the unrecognized and unsupported portion of the extended schema. However, there is no implied guarantee that the extended elements are saved and forwarded by the consumer of the event that does not recognize the extension.

    Versioning

    Multiple versions of the XML schema are supported by appending a version number to the XML schema file name. The current XML file name is therefore, commonbaseevent1_0_1.xsd. Also, the CommonBaseEvent schema provides "version" token in the schema declaration (see Common Base Event XML schema) and a "version" attribute in the CommonBaseEvent element.


    CommonBaseEvent description

    Table 3 is a summary of the CommonBaseEvent properties; that is, the data collected for the situation 3-tuple. As stated earlier, the 3-tuple consists of the ID of the component experiencing the situation, the ID of the component reporting the situation, and the situation itself.

    Table 3. CommonBaseEvent XML properties

    Property name Type Description
    Version xsd:string A string identifying the version of this event. This field is OPTIONAL in that if it is not specified, the version of the Common Base Event is said to be 1.0. Otherwise this field MUST be filled in and MUST be consistent with the version specified in the schema header. The string length for version MUST NOT exceed 16 characters. When an application is creating an event following this version of the specification, this field should be set to 1.0.1.
    localInstanceId xsd:string A source supplied event identifier. There is no guarantee that this value is globally unique. This is an OPTIONAL property. The string length for localInstanceId MUST NOT exceed 128 characters.
    globalInstanceId xsd:ID The primary identifier for the event. This property MUST be globally unique and MAY be used as the primary key for the event. This is an OPTIONAL property. However, once this value is set it MUST never be changed. The recommended value is either a 128- or 256-bit globally unique ID (GUID) and must start with an alphabetic character (for example., a-z and A-Z).
    creationTime xsd:dateTime The date and time when the event was issued. The value MUST be as defined by the XML Schema dateTime data type. The value of the creationTime MUST provide granularity as precisely as the generating platform allows. This is a REQUIRED property.
    severity xsd:short The perceived severity of the status the event is describing with respect to the application that reports the event. The predefined severity levels, in order of increasing severity, are as follows:
    • 0: Unknown
    • 10: Information MUST be used for cases when the event contains only general information and is not reporting an error.
    • 20: Harmless MUST be used for cases in which the error event has no effect on the normal operation of the resource.
    • 30: Warning MUST be used when it is appropriate to let the user decide if an action is needed in response to the event.
    • 40: Minor MUST be used to indicate that action is needed but the situation is not serious at this time.
    • 50: Critical MUST be used to indicate that an immediate action is needed and the scope is broad (perhaps an imminent outage to a critical resource will result).
    • 60: Fatal MUST be used to indicate that an error occurred, but it is too late to take remedial action.
    The associated values are 0 to 70. The reserved values start at 0 for Unknown and increase by increments of 10 to 60 for Fatal. Other severities MAY be added but MUST NOT exceed 70. This is an OPTIONAL property.
    priority xsd:short Defines the importance of the event. The predefined priorities are:
    • 10: Low
    • 50: Medium
    • 70: High
    The values are 0 to 100. The reserved value for Low is 10, for Medium is 50, and for High is 70. Other priorities MAY be added but MUST NOT exceed 100. This is an OPTIONAL property.
    reporterComponentId cbe:ComponentIdentification Identification of the component that is the reporter of the event or the situation. It is a REQUIRED property if the reporting component is different than the source component. Otherwise this field MUST NOT be present.
    sourceComponentId cbe:ComponentIdentification Identification of the component that is affected or impacted by the event or the situation. This is a REQUIRED property for the component that is affected by the situation.
    situation cbe:Situation The situation specifies the type of the situation that caused the event to be reported. This is a REQUIRED property.
    contextDataElements cbe:ContextDataElement An array of contexts that this event is referencing. This is an OPTIONAL property.
    MsgDataElemtn cbe:MsgDataElement Identification of the message that this event holds. This is an OPTIONAL property.
    msg xsd:string The text accompanying the event. This is typically the resolved message string in human readable format rendered for a specific locale. This is an OPTIONAL property. The string length for msg MUST NOT exceed 1024 characters.
    repeatCount xsd:short The number of occurrences of an identical event within a specific time interval. This is an OPTIONAL property with no default. A value of 0 or no value is indicative of no repeat of the event detected.
    elapsedTime xsd:long This is the time interval or the elapsed time during which the number of identical events occurred (as specified by the repeatCount property). This property is expressed in microseconds. If no value (or zero) is specified for repeatCount, this is an OPTIONAL property with no default value. However, if repeatCount is specified (it has a non-zero value), elapsedTime is REQUIRED.
    associatedEvents cbe:AssociatedEvent[] This property allows events to be grouped. This property is a complex type that consists of globalInstanceIds that identify the associated events plus a type field that describes the type of association that is represented by the name of the association. This is an OPTIONAL property.
    extensionName xsd:Name The name of an event class (or element in XML) that this event represents (for example, CommonBaseEvent). The name indicates any additional elements that are expected to be present within the event. This is an OPTIONAL property. If the value specified is null, then the value is assumed to be CommonBaseEvent. The string length for extensionName MUST NOT exceed 64 characters.
    extendedDataElements cbe:ExtendedDataElement[] An array of product specific extensions that allows any other attributes not defined by the CommonBaseEvent. Information placed here is assumed to be product specific data; its interpretation is not specified. This is an OPTIONAL property.
    sequenceNumber xsd:long A source-defined number that allows for multiple messages to be sent and processed in a logical order that is different than the order in which they arrived at the consumer location (for example, an event server or management tools). The sequence number helps consumers to sort arrived messages that might arrive out of order. This is with respect to the creation time and to the particular reporter of the messages. This is an OPTIONAL property with no default value.

    The following sections contain detailed descriptions of these properites

    version

    The version attribute is of type string and is used to identify the version of a given event such that it can be recognized and managed appropriately by receivers of the event.

    This field is OPTIONAL in that if it is not specified, the version of the Common Base Event is said to be 1.0. Otherwise this field MUST be filled in and MUST be consistent with the version specified in the schema header. The string length for version MUST NOT exceed 16 characters. When an application is creating an event following this version of the specification this field should be set to 1.0.1.

    This property is mutable in the case where a migration procedure has upgraded a Common Base Event to a newer version.

    localInstanceId

    The localInstanceId is of type string and is used to locally identify instances of an event. There is no implied guarantee that this value is globally unique but unique within the execution process that generates the event. However, after it is set it MUST remain constant for the lifetime of the event. The value content of the localInstanceId MAY be a multipart value, such a timestamp, location, offset, or message ID and MAY use other application-defined techniques to ensure the uniqueness of the ID values. For example, the identifier value might be set to the string concatenation of the local host IP address, the absolute path of the access.log file, the local fully qualified host name, a time stamp, and the sequenceNumber. The resulting identifier might look as follows:

    9.27.11.27mycomputer.toronto.ibm.com2002100902534.002000-240
    

    This property is not a key. This is an OPTIONAL property that is not mutable; that is, once it is set it MUST NOT be changed. It MAY be provided by the component that issues the event or MAY be assigned by the consumer of the event. The string length for the localInstanceId MUST NOT exceed 128 characters.

    globalInstanceId

    The globalInstanceId is a complex data type that represents the primary identifier for the event. The property globally and uniquely identifies the event and MAY be used as the primary key for the event. The value MUST be a GUID that is at least 128 bits in length but not greater than 256 bits and MUST start with an alphabetic character (for example, A-Z). The GUID generation algorithm MUST ensure the uniqueness of this value.

    One standard for constructing a GUID is defined in the Internet draft draft-leach-uuids-guids-01. This value is computed based on using cryptographic quality random information. This Internet draft does not generate a GUID that starts with an alphabetic character; to use it you MUST prepend it with a single character.

    This is an OPTIONAL property. However, when it is specified it is not mutable; that is, after it is set, it MUST NOT be changed for the lifetime of the event. The globalInstanceId MAY be provided either by the component that issues the event or by the consumer of the event.

    The globalInstanceId is required if associations among events are to be established. If globalInstanceId is not specified, then the association specified by AssociatedEvent (AssociatedEvent description) cannot be used.

    creationTime

    The date and time that the event was created that MUST be specified as defined by the XML Schema dateTime data type. 3 The value of the creationTime MUST provide granularity as precisely as the generating platform allows.

    This is a REQUIRED property that is not mutable (that is, its value MUST NOT be changed for the lifetime of the event) and MUST be provided by the component that reports the event.

    severity

    The severity indicates the event status severity level with respect to the component that reports the event. These values are usually provided by a component's domain expert. The meanings of the values that this property may contain MAY be described by an enumeration of common values or qualifiers that indicate the severity level of the event. For example, information, warning, or a set of integers that map to the intended severity levels are all valid values. This appendix does not imply any specific implementation, but instead suggests the following values based on prior art with the understanding that users of this field MAY add additional implementation-specific values. This field is intended to define the seriousness of the kind of situation that was encountered so that administrators can focus on the most severe problems.

    The predefined severity levels, in order of increasing severity, are as follows:

    The associated values are 0 to 70. The reserved values start at 0 for Unknown and increase by increments of 10 to 60 for Fatal. Other severities MAY be added but MUST NOT exceed 70. If no value is specified, this event is interpreted as having no severity.

    This is an OPTIONAL property and is not mutable once it is set. There is no default value for severity.

    priority

    The priority defines the importance of the event and the relative order in which the event records SHOULD be processed. The predefined priorities are as follows:

    The values are 0 to 100. The reserved value for Low is 10, for Medium is 50, and for High is 70. Other priorities MAY be added but MUST NOT exceed 100.

    If no value is specified, then this event is interpreted as having no priority.

    The priority property is independent of severity, because priority is intended to be used primarily by event consumers, whereas severity indicates the state of the situation as perceived by the affected component. For example, an event with priority HIGH and severity MINOR should be processed before an event with priority LOW and severity CRITICAL.

    This is an OPTIONAL property and it is mutable. There is no default value for the priority.

    reporterComponentId

    The reporterComponentId is the identification of the component that reported the event or situation on behalf of the affected component. The data type for this property is a complex type as described by the ComponentIdentification type that provides the required data to uniquely identify a component.

    It is a REQUIRED property if the reporting component is different than the source component. Otherwise, this field MUST NOT be present. This property is not mutable.

    sourceComponentId

    The sourceComponentId is the identification of the component that was affected or was impacted by the event or situation. The data type for this property is a complex type as described by the ComponentIdentification type that provides the required data to uniquely identify a component.

    This property is REQUIRED and it is not mutable. The producer of the event MUST provide the sourceComponentId. If the reporter and the affected components are the same, then the reporterComponentId MUST NOT be present.

    situation

    The situation is the data that describes the situation or event reported by the event. The situation information includes a required set of properties or attributes that are common across products groups and platforms, yet architected and flexible to allow for adoption to product-specific requirements. The situation is an element of type Situation (see Situation), which specifies the type of the situation that caused the event to be reported.

    This is a REQUIRED property and is not mutable.

    contextDataElements

    The contextDataElements is an array of contexts of type ContextDataElement (see ContextDataElement description) that this event is referencing. This property holds data that is used to assist with problem diagnostics by correlating messages or events generated along the execution path of a unit of work.

    This is an OPTIONAL property and is not mutable. It MAY be provided by the component that issues the event or MAY be assigned by the consumer of the event.

    msg

    The msg property is the text that accompanies the event. This is typically the resolved message string in human-readable format rendered for a specific locale.

    The locale of the msg property is specified by the msgLocale property of the MsgDataElement type (see MsgDataElement description).

    This property is OPTIONAL but RECOMMENDED if the msgCatalogId and msgCatalog properties of the MsgDataElement do not specify any values.

    The string length for msg MUST NOT exceed 1024 characters.

    msgDataElement

    The msgDataElement is a property that is refers to a MsgDataElement. This property holds data that is used to specify all the related information associated with the message that this event holds.

    This is an OPTIONAL property and is not mutable. It is provided by the component issuing the event.

    extensionName

    The extensionName property contains the name of an "event class" that this event represents (for example, Trace, CommonBaseEvent). The event class name is indicative of any additional properties expected to be present within the specific event. If you choose to use ExtendedDataElement, it is RECOMMENDED that you specify a value for the extensionName.

    This is an OPTIONAL property and is not mutable. It can only be provided by the component that reports the event. If the value specified is null, then the value is assumed to be CommonBaseEvent.

    extendedDataElements

    The extendedDataElements property is a sequence of name elements of type ExtendedDataElement (described in ExtendedDataElement description). It offers extensibility by providing a way to specify any other attributes not defined by the CommonBaseEvent data model. Information placed here is assumed to be product-specific data.

    This property is user-supplied; its named elements can be filtered, searched, or referenced by the correlation rules.

    This is an optional property and is mutable. The value for this property MAY be provided by the component that issues the event or the event consumer MAY assign it.

    associatedEvents

    The associatedEvents property allows for event grouping or parent-child relationship. This property is a complex type that consists of globalInstanceIds that identify the associated events (described in AssociatedEvent description).

    This is an OPTIONAL property and is mutable. The value for this property MAY be provided by the component that issues the event or the event consumer MAY assign it.

    repeatCount

    The repeatCount specifies the number of occurrences of identical events within a specified time interval. The time interval is specified by the elapsedTime property described next. The definition of identical events is application specific and therefore is not defined by this specification.

    This property is OPTIONAL and is mutable. The repeatCount property MAY be set by the component that issues the event or the event consumer. There is no default value. A value of 0 or no value indicates no repeated occurrences of the event.

    elapsedTime

    The elapsedTime is the time interval during which some number of identical events occurred. The number of occurrences is specified by the value of the repeatCount. The elapsedTime value indicates the duration of time within which the repeated events were observed.

    The value of this property MUST be expressed in microseconds granularity.

    This property is OPTIONAL and is mutable. However, if the repeatCount is specified, an elapsed time MUST be present. The elapsedTime MUST be set by the same component that sets the repeatCount. There is no default value for elapsedTime.

    sequenceNumber

    The sequenceNumber is a source-defined number that allows multiple messages to be sent and processed in a logical order that might be different than the order in which they arrived at the consumer's location (for example, with event servers or management tools). The sequence number helps consumers to sort messages when they arrive. This is with respect to time and to the particular provider of the event.

    This property is OPTIONAL and it is not mutable. There is no default value.


    ComponentIdentification description

    In the area of problem reporting, two general categories of components that should be considered for problem diagnosis: the component that observes and reports the situation (the reporter component), and the actual component that experiences the situation (the affected component). Component identification provides a collection of attributes that are required to uniquely identify a component. The same data is used to identify both the reporter and the affected component. In some cases, these components might be the same.

    For example, in a typical IT environment the activities of applications running in that environment are monitored using events that are received or collected from the applications using management agents or adapters.

    Table 4 is a summary of the properties for the ComponentIdentification type. A detailed description of the ComponentIdentification properties follows the summary table.

    Table 4. ComponentIdentification properties

    Property name Type Description
    location xsd:string Specifies the physical address that corresponds to the location of a component. For example, host name, IP address, MAC address, or IBM VTAM(R) logical unit (LU). The format of the value of the location is specified by the locationType property. The RECOMMENDED value is a fully qualified host name. This value should be unique within the network that is capable of raising events to a specified receiver. For example, if an adapter were monitoring a router, this attribute SHOULD contain the IP address of the machine where the adapter resides, not the IP address of the router that is having the problem. This is a REQUIRED property. The string length for location MUST NOT exceed 256 characters.
    locationType xsd:Name Specifies the format and meaning of the value in the location property. The reserved keywords for this property are:
    • Unknown
    • IPV4
    • IPV6
    • NWA
    • ISDN
    • ICD
    • OID-OSI
    • Dial
    • HWA
    • HID
    • X25
    • DCC
    • SNA
    • IPX
    • E.164
    • Hostname
    • FQHostname
    • Devicename
    This is a REQUIRED property. The string length for locationType MUST NOT exceed 32 characters. If the location value does not have a well-known type, then the locationType should contain Unknown.
    application xsd:string The name of the application (for example, myWebApp). This is an optional property. The application version information MAY be appended to the end of the component separated by a # character (for example, maWebApp#4.5.1). This is an OPTIONAL property. The string length for application MUST NOT exceed 256 characters.
    executionEnvironment xsd:string This property identifies the immediate environment that an application is running in. For example, a WebSphere Application Server name: cell:node:server. The executionEnvironment version information can be appended to the end of the component separated by a # character. This is an OPTIONAL property. The string length for executionEnvironment MUST NOT exceed 256 characters.
    component xsd:string Specifies the logical identity of a component. This property MUST contain the name of a particular application, product or subsystem (for example, IBM DB2# 7.1). This value SHOULD be unique within the scope specified by the locationType. The component version information MAY be appended to the end of the component name separated by a # character. This is a REQUIRED property. The string length for the component name MUST NOT exceed 256 characters.
    subComponent xsd:string Specifies a further distinction for the logical component property of the event. It SHOULD contain the identity of the subcomponent of the component property. This property MAY be one of the various parts of an application or operating system resource (for example, a module name, a class name, a class and method name, and so on). It SHOULD be the most granular definition specified in the event. The subcomponent version information MAY be appended to the end of the subcomponent name separated by a # character. This is a REQUIRED property. The string length for the subComponent name MUST NOT exceed 512 characters.
    componentIdType xsd:string Specifies the format and meaning of the component identified by this componentIdentification. The non-exclusive reserved keywords for this property are:
    • ProductName
    • DeviceName
    • SystemName
    • ServiceName
    • Process
    • Application
    • Unknown
    This is a REQUIRED property. The string length for componentIdType MUST NOT exceed 32 characters. The default value is "Unknown."
    instanceId xsd:string Specifies a handle or identifier for the instance of the component that is specified by the component property (for example, Grid Service Handle [GSH] or EJBHandle). This is an OPTIONAL property. The string length for instanceId MUST NOT exceed 128 characters.
    processId xsd:string This property identifies the process ID of the running component or subcomponent that generated the event. This is an OPTIONAL property with no default value. The string length for processId MUST NOT exceed 64 characters.
    threadId xsd:string This property identifies the thread ID of the component or subcomponent that generated the event. This value changes with every new thread spawned by the process identified by processId. This is an OPTIONAL property with no default value. The string length for threadId MUST NOT exceed 64 characters.
    componentType xsd:string The componentType is a well-defined name that is used to characterize all instances of a given kind of component. This property is REQUIRED property. The maximum string length for componentType MUST NOT exceed 512 characters.

    location

    The location specifies the physical address that corresponds to the location of a component. Examples of locations include: a host name, IP address, MAC address, or VTAM LU. The format of the value of the location is specified by the locationType property. The RECOMMENDED value is a fully qualified host name.

    This property is REQUIRED and it is not mutable. The string length for location MUST NOT exceed 256 characters.

    locationType

    This property specifies the format and meaning of the value in the location property. The reserved keywords for this property are:

    This property is REQUIRED and is not mutable. The string length for locationType MUST NOT exceed 32 characters. If the location value does not have a well-known type, the locationType MUST contain Unknown.

    application

    The application property specifies the user name of application (for example, myApp). The application version information MAY be appended to the end of the component separated by a # character (for example, myApp#3.2). It is RECOMMENDED that the vendor name be prepended to the application name.

    This is an OPTIONAL property and is not mutable. The string length for the application name MUST NOT exceed 256 characters.

    executionEnvironment

    The executionEnvironment property identifies the immediate environment that an application is running in. For example, a WebSphere Application Server name: cell:node:server.

    The executionEnvironment version information MAY be appended to the end of the component separated by a # character (for example, thiscell:thisnode:thisserver#5.3.2). The string length for executionEnvironment MUST NOT exceed 256 characters.

    This is an OPTIONAL property and is not mutable.

    component

    The component specifies the logical identity of a component. This property MUST contain the name of a particular application, product, or subsystem (for example, IBM DB2#7.1). This value SHOULD be unique within the scope specified by the reporter location.

    This property is REQUIRED and is not mutable. The string length for the component name MUST NOT exceed 256 characters.

    subComponent

    The subComponent specifies a further distinction for the logical component property of the event.

    It SHOULD contain the identity of the subcomponent of the component property and it SHOULD be the most granular definition specified in the event. This property MAY be one of the various parts of an application or operating system resource such as a module name, class name, class, method name, and so on.

    This property is REQUIRED and it is not mutable. The string length for the subComponent name MUST NOT exceed 512 characters.

    componentIdType

    The componentIdType specifies the format and meaning of the component identified by this componentIdentification. The reserved, nonexclusive list of keywords for this property are:

    This property is REQUIRED and it is not mutable. The string length for componentIdType MUST NOT exceed 32 characters.

    instanceId

    The instanceId specifies a handle or identifier for the instance of the component that is specified by the component property, for example, Grid Service Handle (GSH), 4 EJBHandle, and so on.

    This property is OPTIONAL and is not mutable. The string length for instanceId MUST NOT exceed 128 characters.

    processId

    The processId is a string type that identifies the process ID of the running component or subcomponent that generated the event. The value is platform-specific.

    This is an OPTIONAL property that is not mutable. The string length for processId MUST NOT exceed 64 characters.

    threadId

    The threadId property is of type string and identifies the thread ID of the component or subcomponent indicated by the process ID that generated the event. A running process may spawn one or more threads to execute its functions. Therefore, the thread ID will change accordingly. The value is platform-specific.

    This is an OPTIONAL property that is not mutable. The string length for threadId MUST NOT exceed 64 characters.

    componentType

    The componentType is a well-defined name (syntax and semantics) that is used to characterize all instances of a given kind of component. For details of the contents of this property, refer to the componentType entry in Component type namespace.

    This property is REQUIRED and it is not mutable; that is, once it is set it MUST NOT be changed. The maximum string length for componentType MUST NOT exceed 512 characters.


    Situation

    Table 5 is a summary of the properties for the Situation type. A detailed description of the Situation properties follows the summary table.

    Table 5. Situation properties

    Property name Type Description
    situationType cbe:SituationType The situationType specifies the type of the situation that caused the event to be reported. This is an REQUIRED property.
    categoryName xsd:string The categoryName specifies the type of the situation that caused the event to be reported. The categoryName is a string and has the following set of values:
    • StartSituation
    • StopSituation
    • ConnectSituation
    • ConfigureSituation
    • RequestSituation
    • FeatureSituation
    • DependencySituation
    • CreateSituation
    • DestroySituation
    • ReportSituation
    • AvailableSituation
    • OtherSituation
    This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.

    categoryName

    This property categorizes the type of the situation that caused the event to be reported. The categoryName property has the following set of values:

    This is a REQUIRED property and once it is set it is not mutable.


    situationType

    The situationType specifies the type or category of the situation that caused the event to be reported. The categorization of situations facilitates the building of tools that focus on implementing the analysis and planning functions rather than on product-specific data formats. The data type for this property is a complex type. The situation types or categories are defined below. SituationType is an abstract element that is used to define all supported situation types (for example, StartSituation, StopSituation, and so on).

    The simplest way to understand the usefulness of categorization is by providing a use case. For example, assume that a problem has been detected with component A. The first step in the root-cause analysis might be to check to see if x was actually started, because it is known that A has a dependency on x. One approach to determine if x is running is to check the log file for x to see if it has started. The problem from a programmatic perspective is that there is not standard way to check the log files to see if x has started. x might log "Component x started" or it might say, "Change server state from starting to running." The reality is that both of these messages provide the same information, but they provide it using different terminology, making it difficult for a program to use. Simple checks like this would be much easier if all components reported, for example, that they "started." Writing code to check dependencies would be much easier and would be, largely, component independent. For example, if product A had dependencies on x and y, the code to check the status of x and the code to check the status of y would be the same, in both cases, it would look for a "started" message.

    This is a REQUIRED property and after it is set it is not mutable.

    The following sections outline the well-known and acceptable values for the situationType Table 6).

    Table 6. situationType property

    Property name Type Description
    reasoningScope xsd:string This property specifies the scope of the impact of the situation reported. The initial set of values is described following this table. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.

    reasoningScope

    This is a REQUIRED property and once it is set it MUST NOT change. This property specifies the scope of the situation. The reasoningScope defines whether this situation has an internal only impact or has a potential external impact. The reasoningScope is of type SituationReasoningScopeType and has the following initial set of values:

    StartSituation

    The StartSituation deals with the start up process for a component. Messages that indicate that a component has begun the startup process, that it has finished the startup process, or that it has aborted the startup process all fall into this category. Existing messages include words like starting, started, initializing, and initialized, for example:

    DIA3206I The TCP/IP protocol support was started successfully.
    DIA3000I "%1S" protocol support was successfully started.
    DIA3001E "%1S" protocol support was not successfully started.
    WSVR0037I: Starting EJB jar: {0}
     
    

    Table 7 shows the StartSituation properties.

    Table 7. StartSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and once it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    situationQualifier xsd:string This property specifies the situation qualifiers that are representation of the parameters necessary to describe the situation. The situationQualifier is a string with the following set of values:
    • START INITIATED
    • RESTART INITIATED
    • START COMPLETED
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    StopSituation

    The StopSituation deals with the shutdown process for a component. Messages that indicate that a component has begun to stop, that it has stopped, or that the stopping process has failed all fall into this category. Existing messages include words like stop, stopping, stopped, completed, and exiting, for example:

    WSVR0220I: Application stopped: {0}
    WSVR0102E: An error occurred stopping, {0}
    MSGS0657I: Stopping the MQJD JMS Provider
     
    

    Table 8 shows the StopSituation properties.

    Table 8. StopSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    situationQualifier xsd:string This property specifies the situation qualifiers that are representation of the parameters necessary to describe the situation. The situationQualifier is a string with the following set of values:
    • STOP INITIATED
    • ABORT INITIATED
    • PAUSE INITIATED
    • STOP COMPLETED
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    ConnectSituation

    The ConnectSituation deals with the situations that identify aspects about a connection to another component. Messages that say a connection failed, that a connection was created, or that a connection was ended all fall into this category. Existing messages include words like connection reset, connection failed, and failed to get a connection, for example:

    DBMN0015W: Failure while creating connection {0}
    DBMN0033W: connection close failure {0}
    DBMN0023W: Failed to close a connection {0}
     
    

    Table 9 shows the ConnectSituation properties.

    Table 9. ConnectSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    situationDisposition xsd:string This property specifies the situation disposition that is representation of the parameters necessary to describe the situation. The situationDisposition is a string with the following set of values:
    • INUSE
    • FREED
    • CLOSED
    • AVAILABLE
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    RequestSituation

    The RequestSituation deals with the situations that a component uses to identify the completion status of a request. Typically, these requests are complex management tasks or transactions that a component undertakes on behalf of a requestor and not the mainline simple requests or transactions. Existing messages include words like configuration synchronization started, and backup procedure complete, for example:

    ADMS0003I: Configuration synchronization completed
    

    Table 10 shows the RequestSituation properties.

    Table 10. RequestSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and once it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    situationQualifier xsd:string This property specifies the situation qualifiers that are representation of the parameters necessary to describe the situation. The situationQualifier is a string with the following set of values:
    • STOP INITIATED
    • ABORT INITIATED
    • PAUSE INITIATED
    • STOP COMPLETED
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    ConfigureSituation

    The ConfigureSituation deals with the components identifying their configuration. Any changes that a component makes to its configuration should be logged using this category. Additionally, messages that describe current configuration state fall into this category. Existing message include words like port number is, address is, and process id, for example:

    ADFS0134I: File transfer is configured with host="9.27.11.13", port="9090", 
    securityEnabled="false".
    

    Table 11 shows the ConfigureSituation properties.

    Table 11. ConfigureSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    AvailableSituation

    The AvailableSituation deals with the situations reported from the component, regarding its operational state and availability. This situation provides a context for operations that can be performed on the component by distinguishing if a product is installed, operational and ready to process functional requests, or operational and ready/not ready to process management requests. Existing message include words like those that now ready to take requests, online, and offline, for example:

    ADMC0013I: SOAP connector available at port 8880
    ADMC0026I: RMI Connector available at port 2809
     
    

    Table 12 shows the AvailableSituation properties.

    Table 12. AvailableSituation properties

    Property name Type Description
    operationDisposition xsd:string This property specifies the operation state of the component reported by the situation. The operationalDisposition is a string with the following set of values:
    • STARTABLE
    • NONSTARTABLE
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    availabilityDisposition xsd:string This property specifies the availability disposition of an entity or component that caused the situation to be reported. The availabilityDisposition is a string with the following set of values:
    • AVAILABLE
    • NOT AVAILABLE
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.
    processingDisposition xsd:string This property specifies the processing disposition of a component operation that caused the situation to be reported. The processingDisposition is a string with the following set of values:
    • FUNCTION_PROCESS
    • FUNCTION_BLOCK
    • MGMTTASK_PROCESS
    • MGMTTASK_BLOCKED
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    ReportSituation

    The ReportSituation deals with the situations reported from the component, such as heartbeat or performance information. Data such as current CPU utilization, current memory heap size, and so on would fall into this category. Existing messages include words like utilization value is, buffer size is, and number of threads is, for example:

    IEE890I WTO Buffers in console backup storage = 1024
    

    Table 13 shows the ReportSituation properties.

    Table 13. ReportSituation properties

    Property name Type Description
    reportCategory xsd:string This property specifies the category of the reported situation. The reportCategory is a string with the following set of values:
    • PERFORMANCE
    • SECURITY
    • HEARTBEAT
    • STATUS
    • TRACE
    • DEBUG
    • LOG
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    CreateSituation

    The CreateSituation deals with the situations documenting when a component creates an entity. Messages telling that a document was created, or a file was created, or an EJB was created all fall into this category. Existing message include words like was created, about to create, and now exists, for example:

    ADMR0009I: Document cells/flatfootNetwork/applications/Dynamic Cache Monitor.ear/Dynamic 
    Cache Monitor.ear was created
    

    Table 14 shows the CreateSituation properties.

    Table 14. CreateSituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    DestroySituation

    The DestroySituation deals with the situations documenting when an entity or component was removed or destroyed. Messages telling that a document was destroyed or a file was deleted all fall into this category. Existing message include words like was created, about to create, and now exists, for example:

    CONM6007I: The connection pool was destroyed for data source (UDDI.Datasource.techs8.server1).
    

    Table 15 shows the DestroySituation properties.

    Table 15. DestroySituation properties

    Property name Type Description
    successDisposition xsd:string This property specifies the success disposition of an operation of a situation that caused the situation to be reported. The successDisposition is a string with the following set of values:
    • SUCCESSFUL
    • UNSUCCESSFUL
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    FeatureSituation

    The FeatureSituation deals with the situations that announce that a feature of a component is now ready (or not ready) for service requests. Situations that indicate things like services being available and services or features being unavailable fall into this category. Existing situations include words like now available, currently available, and transport is listening on port 123, for example:

    SRVE0171I: Transport HTTPS is listening on port 9443 
    MSGS0601I: WebSphere Embedded Messaging has not been installed
     
    

    Table 16 shows the FeatureSituation properties.

    Table 16. FeatureSituation properties

    Property name Type Description
    featureDisposition xsd:string This property specifies the availability disposition of a feature of a component that caused the situation to be reported. The featureDisposition is a string with the following set of values:
    • AVAILABLE
    • NOT AVAILABLE
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    DependencySituation

    The DependencySituation deals with the situations that components produce to say that they cannot find some component or feature that they need. This category includes messages about not finding the version of the component that was expected. Messages that say a resource was not found, or that an application or subsystem that was unavailable, also fall into this category. Existing messages include words like could not find, and no such component, for example:

    WSVR0017E: Error encountered binding the J2EE resource, Pet Store JMS Queue Connection Factory, 
    as jms/queue/QueueConnectionFactory from resources.xml no resource binder found
    

    Table 17 shows the DependencySituation properties.

    Table 17. DependencySituation properties

    Property name Type Description
    dependencyDisposition xsd:string This property specifies the dependency disposition of a feature of a component that caused the situation to be reported. The dependencyDisposition is a string with the following set of values:
    • MET
    • NOT MET
    This is a REQUIRED property and after it is set it MUST NOT change. The string length for this property MUST NOT exceed 64 characters.

    OtherSituation

    The OtherSituation category is to provide support for the situation that is product-specific requirement other than the predefined categories.

    ExtendedDataElement description

    The ExtendedDataElement allows for application-supplied name-type-value collections to be specified for extensibility purposes. This is the mechanism by which other attributes not specified in the CommonBaseEvent data model can be added. Collections specified here are assumed to be product-specific data.

    Table 18 is a summary of the properties for the ExtendedDataElement type. A detailed description of the ExtendedDataElement properties follows the summary table.

    The named properties can be filtered, searched, or referenced by the correlation rules. The name is user-defined; however, the nonexclusive reserved keywords are as follows:


    Table 18. ExtendedDataElement properties

    Property name Type Description
    name xsd:Name The name of the extended data element. This name MUST be unique with respect to all other fields at the same level of extendedDataElement hierarchy, however, there might exist a child with the same name at different level or hierarchy. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    type xsd:Name The data type of the values specified in the values property. Valid types are as follows:
    • byte, short, int, long, float, double
    • string
    • dateTime
    • byteArray, shortArray, intArray, longArray, floatArray, doubleArray
    • stringArray
    • dateTimeArray, durationArray
    • hexBinary
    • boolean, booleanArray
    • noValue
    These are the only valid data types for the ExtendedDataElement type. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    values xsd:string[] The array of values for this extended data element represented as a string of the specified type, excluding hexBinary. hexBinary values MUST be defined using the hexValue property. The hexValue and the values properties are mutually exclusive. Only one of these properties SHALL be defined. This is an OPTIONAL property. The string length for this property MUST NOT exceed 1024 characters.
    hexValue xsd:hexBinary The hexValue is an array of characters that holds the data for any other data type or complexType not in the supported types described above. The hexValue and the values properties are mutually exclusive. Only one of these properties SHALL be defined. This is an OPTIONAL property.
    children cbe:ExtendedDataElement[] Contains other extendedDataElement(s) to specify a structured list of extendedDataElements. This list allows a reporter to create a hierarchy of extendedDataElements for a specific CommonBaseEvent. This is an OPTIONAL property.

    name

    The name property specifies the name of the ExtendedDataElement (including RawData, msgLocale, and EventStatus). This name MUST be unique with respect to all other properties at the same level of extendedDataElement hierarchy, however, there may exist a child with the same name at different level.

    This property is REQUIRED and is not mutable. The string length for this property MUST NOT exceed 64 characters.

    type

    Valid data types for the values of the property are as follows:

    These data types are the only valid types for the ExtendedDataElement type.

    The default value is string. The type noValue is a reserved string to identify cases where an ExtendedDataElement contains only children and no data.

    This property is REQUIRED and is not mutable. The string length for this property MUST NOT exceed 64 characters.

    values

    An array of values for this extended data element of the type defined by the type property just described.

    This property is OPTIONAL and it is mutable. It MUST NOT be specified if the hexValue property is specified.

    Note:
    The hexValue and values properties are mutually exclusive. Only one of these two properties SHALL be defined.

    hexValue

    The hexValue property is an array of characters that holds the data of type hexBinary for all other data types or complexTypes not in the supported list of types defined above.

    This property is OPTIONAL and is not mutable. It MUST NOT be specified if the values property is specified.

    Note:
    The hexValue and values properties are mutually exclusive. Only one of these two properties SHALL be defined.

    children

    The children property refers to other ExtendedDataElement(s) to specify a structured list of ExtendedDataElements. This list allows for the creation of a hierarchy of related ExtendedDataElements corresponding to a specific group of CommonBaseEvents. Accordingly, this is an efficient and quick way to get access to the list of related ExtendedDataElements without having to look through and examine all the ExtendedDataElements.

    This property is OPTIONAL and it is mutable.

    ContextDataElement description

    The ContextDataElement type defines the contexts that this event references. This complex type holds data that is used to assist with problem diagnostics by correlating messages or events generated during execution of a unit of work.

    Table 19 provides a summary of the data properties representing a context in the CommonBaseEvent. A detailed description of the ContextDataElement follows the summary table.

    Table 19. ContextDataElement properties

    Property name Type Description
    type xsd:Name The data type of the contextValue property. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    name xsd:Name Name of the application that created this context data element. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    contextValue xsd:string The value of the context with respect to the implementation of the context. This is REQUIRED unless contextId specifies a value. The string length for this property MUST NOT exceed 1024 characters.
    contextId xsd:NMTOKEN This property is the reference to the globally unique identifier of the element that contains the context. This is REQUIRED unless contextValue specifies a value.

    type

    This is the data type of the context. This type should allow the consumer of the event to recognize the format of the context value. The type is application-specific (for example, PD_LogRecordCorrelator).

    This property is REQUIRED and is not mutable. The string length for this property MUST NOT exceed 64 characters.

    name

    This is the name of the application that created this context data element (for example, Correlation engine).

    This property is REQUIRED and not mutable. The string length for this property MUST NOT exceed 64 characters.

    contextValue

    This is the value of the context with respect to the implementation of the context.

    This property is REQUIRED unless contextId specifies a value and is not mutable. It SHOULD NOT be specified if the contextId property is specified. The string length for this property MUST NOT exceed 1024 characters.

    contextId

    This property is the reference to the element that contains a product- or user-specific context.

    This property is REQUIRED unless contextValue specifies a value and it is not mutable. It MUST NOT be specified if the contextValue property is specified.

    Note:
    The contextValue and the contextId are mutually exclusive. Only one of these two properties SHALL be defined. However, if contextValue is set, then contextId is ignored.

    AssociatedEvent description

    The AssociatedEvent type allows for associated events to be grouped. It allows for identifying associated events and its associationEngine. The associationEngine MAY be the reference to the application that created the association.

    Table 20 provides a summary of the data properties representing an event association in the Common Base Event. A detailed description of the AssociatedEvent follows the summary table.

    Table 20. AssociatedEvent properties

    Property name Type Description
    associationEngine xsd:NMTOKEN Reference to the assocationEngine that created this AssociatedEvent. The associationEngine and associationEngineInfo properties are mutually exclusive. One of these properties MUST be defined.
    associationEngineInfo cbe:associationEngine Identifies the application that establishes association among related or associated events. In addition, it provides properties to describe the type of the association. The associationEngine and associationEngineInfo properties are mutually exclusive. One of these properties MUST be defined.
    resolvedEvents xsd:NMTOKENS Array of globalInstanceIds corresponding to the events that are associated with this event. This is a REQUIRED property and an array with at least one element.

    associationEngine

    This is a reference to the assocationEngine that identifies the application that created this AssociatedEvent.

    The associationEngine and associationEngineInfo properties are mutually exclusive. One of these properties MUST be defined. This property is not mutable.

    associationEngineInfo

    This property identifies the application that establishes association among related or associated events and is of type associationEngine (see associationEngine description). In addition, it provides properties to describe the type of the association.

    The associationEngine and associationEngineInfo properties are mutually exclusive. One of these properties MUST be defined. This property is not mutable.

    resolvedEvents

    An array of globalInstanceIds corresponding to the events that are associated with this event.

    This is a REQUIRED property, an array of NMTOKENS with a minimum of one element. It is provided by the association engine specified by the name property. This property is mutable.

    associationEngine description

    The associationEngine identifies the application that establishes association among related or associated events. In addition, it provides properties to describe the type of the association. The associationEngine is a standalone entity in the XML schema and the AssociatedEvents created by the application that is identified by the associationEngine refer to it. This eliminates the need to repeat the same data in every associated event.

    Table 21 provides a summary of the properties representing an association source in the Common Base Event.

    Table 21. AssociatedEngine properties

    Property name Type Description
    name xsd:Name Name of the application that creates the association. This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    type xsd:Name This property should contain the type of association created by this associationEngine. Some well-defined associations are:
    • Contains
    • Cleared
    • CausedBy
    • MultiPart
    • Correlated
    This is a REQUIRED property. The string length for this property MUST NOT exceed 64 characters.
    id xsd:ID The primary identifier for the element. This property MUST be globally unique. The recommend value for this is either a 128- or 256-bit GUID (represented as a hex string). After this value is set it MUST never be changed. This is a REQUIRED property.

    name

    Name of the application that will create the association.

    This is a REQUIRED property and is not mutable. The string length for this property MUST NOT exceed 64 characters.

    type

    This property SHOULD contain the type of association created by this associationEngine. Some well-defined associations are:

    This is a REQUIRED property and is not mutable if it is set for a specific name property. The string length for this property MUST NOT exceed 64 characters.

    id

    The primary identifier for the element. This property MUST be globally unique. The recommend value for this is either a 128- or 256-bit GUID (represented as a hex string). After this value is set it MUST never be changed.

    This is a REQUIRED property and is not mutable.

    MsgDataElement description

    MsgDataElement represents the data that is used to specify all of the related information that is associated with the message that this event holds.

    Table 22 provides a summary of the data properties representing a message in the Common Base Event. A detailed description of MsgDataElement follows the summary table.

    Table 22. MsgDataElement properties

    Property name Type Description
    msgId xsd:string Specifies the message identifier of the event. This identifier SHOULD be a unique value string of alphanumeric or numeric characters. It can be as simple as a string of numeric characters that identify a message in a message catalog or a multipart string of alphanumeric characters (for example, DBT1234E). This is an OPTIONAL property. The string length for msgId MUST NOT exceed 256 characters.
    msgIdType xsd:Name Specifies the meaning and format of the msgId. If the msgId conforms to or represents a standard or a well-known convention, it is named by this property. Examples are: IBM3.4, IBM4.4, IBM3.1.4, IBM3.4.1, IBM4.4.1, and IBM3.1.4.1. The nonexclusive reserved keywords include:
    • IBM* (* is as described above)
    • JMX
    • DottedName
    • Unknown
    This is an OPTIONAL property. The string length for msgIdType MUST NOT exceed 32 characters.
    msgCatalogId xsd:string The index or the identifier for a message that is used for resolving the message text from a message catalog. This is an OPTIONAL property. The string length for this property MUST NOT exceed 64 characters.
    msgCatalogTokens string[] An array of strings used as substitution values for resolving an internationalized message into formatted text. The order of the substitution values is implied by the implicit order of the array elements. If there are no substitution values, then msgCatalogTokens does not need to be specified. This is an OPTIONAL property. The string length for the msgCatalogTokens property MUST NOT exceed 256 characters per token.
    msgCatalog xsd:string The qualified name of the message catalog that contains the translated message specified by the msgCatalogId. This is an OPTIONAL property. The string length of the msgCatalog MUST NOT exceed 128 characters.
    msgCatalogType xsd:Name The msgCatalogType property specifies the meaning and format of the msgCatalog. The current nonexclusive list of reserved keywords includes:
    • Java
    • XPG
    This property is OPTIONAL and it is not mutable once it is set. The string length for the msgCatalogType property MUST NOT exceed 32 characters.
    msgLocale xsd:language The locale for which this msg property is rendered. Its value is a locale code that conforms to IETF RFC 1766. This is an OPTIONAL property.

    msgId

    The msgId property specifies the message identifier for the event. This identifier SHOULD be a unique value string of alphanumeric or numeric characters. It can be as simple as string of numeric characters identifying a message in a message catalog or a multipart string of alphanumeric characters (for example, DBT1234E). The format for msgId is specified by the msgIdType property as described in the next section.

    This is an OPTIONAL property and is not mutable. It SHOULD be provided by the component that issues the event. The string length for the msgId property MUST NOT exceed 256 characters.

    msgIdType

    The msgIdType property specifies the meaning and format of the msgId. If the ID conforms to or represents a standard or a well-known convention, it is named by this property. For example, IBM3.4.1 specifies a message ID of a three-part, eight-character string identifier, consisting of three alphabetic characters representing a component, followed by four numeric characters, and suffixed with one alphabetic character (for example, DBT2359I). Other similar reserved keywords are IBM3.4, IBM4.4, IBM3.1.4, IBM3.4.1, IBM4.4.1, and IBM3.1.4.1.

    The current nonexclusive list of reserved keywords includes:

    This is an OPTIONAL property that is not mutable; that is, once it is set it MUST NOT be changed. It SHOULD be provided by the component that issues the event. It must be provided if msgId property is specified. The string length for the msgIdType property MUST NOT exceed 32 characters.

    msgLocale

    The msgLocale property specifies the locale for which the msg is rendered. Its value is a locale code that conforms to the IETF RFC 1766 specifications. For example, en-US is the value for United State English.

    This property is OPTIONAL and is not mutable. If msgLocale is not specified, it is up to the consumer of the event to decide the locale.

    The string length per msgLocale MUST NOT exceed 11 characters.

    msgCatalogId

    The msgCatalogId property is the index or the identifier for a message that is used to resolve the message text from a message catalog. The msgCatalogId, msgCatalog, and msgCatalogType are mutually dependant; when one has a value, the other two SHOULD contain a value.

    This property is OPTIONAL and is not mutable. The string length for this property MUST NOT exceed 64 characters.

    msgCatalogTokens

    The msgCatalogTokens property consists of an array of string values that holds substitution data used to resolve an internationalized message into a fully formatted text. The order of the values is implied by the implicit order of the array elements. The Locale of the tokens SHOULD be the same as the locale of the message text, defined by msgLocale.

    This property is OPTIONAL and is not mutable. If there are no substitution values, this property does not need to be specified. The string length of the msgCatalogTokens property MUST NOT exceed 256 characters per token.

    msgCatalog

    The msgCatalog property is the qualified name of the message catalog that contains the translated message specified by msgCatalogId. The msgCatalog, msgCatalogType, and msgCatalogId, are mutually dependant; when one has a value, the other two SHOULD contain a value.

    This property is OPTIONAL and is not mutable. The string length for the msgCatalog property MUST NOT exceed 128 characters.

    msgCatalogType

    The msgCatalogType property specifies the meaning and format of the msgCatalog. The current nonexclusive list of reserved keywords includes:

    This property is OPTIONAL, is not mutable once it is set, and MUST be provided if msgCatalog property is defined. The string length for the msgCatalogType property MUST NOT exceed 32 characters.

    Common Base Event XML schema

    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:cbe="http://www.ibm.com/AC/commonbaseevent1_0_1" 
    targetNamespace="http://www.ibm.com/AC/commonbaseevent1_0_1" version="1.0.1" 
    elementFormDefault="qualified">
    	<xsd:complexType name="CommonBaseEventType">
    		<xsd:sequence>
    <xsd:element name="contextDataElements" type="cbe:ContextDataElementType" minOccurs="0" 
    maxOccurs="unbounded" />
    <xsd:element name="extendedDataElements" type="cbe:ExtendedDataElementType" minOccurs="0" 
    maxOccurs="unbounded" />
    <xsd:element name="associatedEvents" type="cbe:AssociatedEventType" 
    minOccurs="0" maxOccurs="unbounded" />
    <xsd:element name="reporterComponentId" type="cbe:ComponentIdentificationType" 
    minOccurs="0" maxOccurs="1" />
    <xsd:element name="sourceComponentId" type="cbe:ComponentIdentificationType" 
    minOccurs="1" maxOccurs="1" />
    <xsd:element name="msgDataElement" type="cbe:MsgDataElementType" 
    minOccurs="0" maxOccurs="1" />
    		<xsd:element name="situation" type="cbe:Situation" 
    		minOccurs="1" maxOccurs="1" />
    		<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" 
    		processContents="skip" />
    		</xsd:sequence>
    		<xsd:attribute name="version" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="16"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="globalInstanceId" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:ID">
    					<xsd:minLength value="32"></xsd:minLength>
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="extensionName" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:Name">
    					<xsd:maxLength value="64" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="localInstanceId" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="128" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="creationTime" type="xsd:dateTime" use="required" />
    		<xsd:attribute name="severity" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:short">
    					<xsd:minInclusive value="0" />
    					<xsd:maxInclusive value="70" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="msg" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="1024" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="priority" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:short">
    					<xsd:minInclusive value="0" />
    					<xsd:maxInclusive value="100" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="sequenceNumber" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:long">
    					<xsd:minInclusive value="0" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<!-- 
    			This attribute has been replaced for version 1.0.1 of the Common Base Event Schema.
    			For version 1.0.1 the attribute categoryName should be filled in with a value that 
    			was assigned to the attribute situationType
    			
    			<xsd:attribute name="situationType" use="optional">
    			<xsd:simpleType>
    			<xsd:restriction base="xsd:string">
    			<xsd:maxLength value="512" />
    			</xsd:restriction>
    			</xsd:simpleType>
    			</xsd:attribute> 
    		-->
    		<xsd:attribute name="repeatCount" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:short">
    					<xsd:minInclusive value="0" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="elapsedTime" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:long">
    					<xsd:minInclusive value="0" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:element name="CommonBaseEvent" type="cbe:CommonBaseEventType" />
    	<xsd:complexType name="ComponentIdentificationType">
    		<xsd:attribute name="component" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="256" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="subComponent" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="512" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="componentIdType" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="32" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="instanceId" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="128" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="application" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="256" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="executionEnvironment" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="256" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="location" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="256" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="locationType" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:Name">
    					<xsd:maxLength value="32" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="processId" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="threadId" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="componentType" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="512" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:complexType name="MsgDataElementType">
    		<xsd:sequence>
    			<xsd:element name="msgCatalogTokens" minOccurs="0" maxOccurs="unbounded">
    				<xsd:complexType>
    					<xsd:attribute name="value" use="required">
    						<xsd:simpleType>
    							<xsd:restriction base="xsd:string">
    								<xsd:maxLength value="256" />
    							</xsd:restriction>
    						</xsd:simpleType>
    					</xsd:attribute>
    				</xsd:complexType>
    			</xsd:element>
    			<xsd:group ref="cbe:msgIdGroup" minOccurs="0" maxOccurs="1" />
    			<xsd:group ref="cbe:msgCatalogGroup" minOccurs="0" maxOccurs="1" />
    		</xsd:sequence>
    		<xsd:attribute name="msgLocale" use="optional">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:language">
    					<xsd:maxLength value="11"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:group name="msgCatalogGroup">
    		<xsd:sequence>
    			<xsd:element name="msgCatalogId" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:string">
    						<xsd:maxLength value="128"></xsd:maxLength>
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    			<xsd:element name="msgCatalogType" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:string">
    						<xsd:maxLength value="32" />
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    			<xsd:element name="msgCatalog" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:string">
    						<xsd:maxLength value="128" />
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    		</xsd:sequence>
    	</xsd:group>
    	<xsd:group name="msgIdGroup">
    		<xsd:sequence>
    			<xsd:element name="msgId" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:string">
    						<xsd:maxLength value="256" />
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    			<xsd:element name="msgIdType" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:Name">
    						<xsd:maxLength value="32" />
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    		</xsd:sequence>
    	</xsd:group>
    	<xsd:complexType name="AssociatedEventType">
    		<xsd:choice minOccurs="1" maxOccurs="1">
    <xsd:element name="associationEngineInfo" type="cbe:AssociationEngineType" 
    minOccurs="1" maxOccurs="1" />
    			<xsd:element name="associationEngine" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:NMTOKEN">
    						<xsd:minLength value="32"></xsd:minLength>
    						<xsd:maxLength value="64"></xsd:maxLength>
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    		</xsd:choice>
    		<!-- This association would contain a serialized version of the GloballyUniqueId for all 
    		the resolvedAssociatedEvent objects -->
    		<xsd:attribute name="resolvedEvents" type="xsd:NMTOKENS" use="required" />
    	</xsd:complexType>
    	<xsd:complexType name="AssociationEngineType">
    <!-- This id would contain a serialized version of the GloballyUniqueId for all the 
    resolvedAssociatedEvent objects -->
    		<xsd:attribute name="id" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:NMTOKEN">
    					<xsd:minLength value="32"></xsd:minLength>
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="type" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:Name">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="name" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:Name">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:element name="associationEngine" type="cbe:AssociationEngineType" />
    	<xsd:complexType name="ExtendedDataElementType">
    		<xsd:sequence>
    			<xsd:choice minOccurs="0" maxOccurs="1">
    				<xsd:element name="values" minOccurs="1" maxOccurs="unbounded">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="1024"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:element>
    			<xsd:element name="hexValue" type="xsd:hexBinary" minOccurs="1" maxOccurs="1" />
    			</xsd:choice>
    <xsd:element name="children" type="cbe:ExtendedDataElementType" 
    minOccurs="0" maxOccurs="unbounded" />
    		</xsd:sequence>
    		<xsd:attribute name="name" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="type" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64"></xsd:maxLength>
    					<!-- Added type noValue when only a children is specified.  -->
    <!-- With a new type noValue, so the value is ignored and only the children is 
    considered. V1.1 Approved -->
    					<xsd:enumeration value="noValue"></xsd:enumeration>
    					<xsd:enumeration value="byte"></xsd:enumeration>
    					<xsd:enumeration value="short"></xsd:enumeration>
    					<xsd:enumeration value="int"></xsd:enumeration>
    					<xsd:enumeration value="long"></xsd:enumeration>
    					<xsd:enumeration value="float"></xsd:enumeration>
    					<xsd:enumeration value="double"></xsd:enumeration>
    					<xsd:enumeration value="string"></xsd:enumeration>
    					<xsd:enumeration value="dateTime"></xsd:enumeration>
    					<xsd:enumeration value="boolean"></xsd:enumeration>
    					<xsd:enumeration value="byteArray"></xsd:enumeration>
    					<xsd:enumeration value="shortArray"></xsd:enumeration>
    					<xsd:enumeration value="intArray"></xsd:enumeration>
    					<xsd:enumeration value="longArray"></xsd:enumeration>
    					<xsd:enumeration value="floatArray"></xsd:enumeration>
    					<xsd:enumeration value="doubleArray"></xsd:enumeration>
    					<xsd:enumeration value="stringArray"></xsd:enumeration>
    					<xsd:enumeration value="dateTimeArray"></xsd:enumeration>
    					<xsd:enumeration value="booleanArray"></xsd:enumeration>
    					<xsd:enumeration value="hexBinary"></xsd:enumeration>
    					<xsd:minLength value="1"></xsd:minLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:complexType name="ContextDataElementType">
    		<xsd:choice minOccurs="1" maxOccurs="1">
    			<xsd:element name="contextValue" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:string">
    						<xsd:maxLength value="1024"></xsd:maxLength>
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    			<xsd:element name="contextId" minOccurs="1" maxOccurs="1">
    				<xsd:simpleType>
    					<xsd:restriction base="xsd:NMTOKEN">
    						<xsd:minLength value="32"></xsd:minLength>
    						<xsd:maxLength value="64"></xsd:maxLength>
    					</xsd:restriction>
    				</xsd:simpleType>
    			</xsd:element>
    		</xsd:choice>
    		<xsd:attribute name="name" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    		<xsd:attribute name="type" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:complexType name="CommonBaseEventsType">
    		<xsd:sequence>
    			<xsd:element ref="cbe:associationEngine" minOccurs="0" maxOccurs="unbounded" />
    			<xsd:element ref="cbe:CommonBaseEvent" minOccurs="0" maxOccurs="unbounded" />
    		</xsd:sequence>
    	</xsd:complexType>
    	<xsd:element name="CommonBaseEvents" type="cbe:CommonBaseEventsType" />
     
    	<xsd:complexType name="Situation">
    		<xsd:sequence>
    		<xsd:element name="situationType" type="cbe:SituationType" minOccurs="1" maxOccurs="1" />
    		</xsd:sequence>
    		<xsd:attribute name="categoryName" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:enumeration value="StartSituation" />
    					<xsd:enumeration value="StopSituation" />
    					<xsd:enumeration value="FeatureSituation" />
    					<xsd:enumeration value="DependencySituation" />
    					<xsd:enumeration value="RequestSituation" />
    					<xsd:enumeration value="ConfigureSituation" />
    					<xsd:enumeration value="ConnectSituation" />
    					<xsd:enumeration value="CreateSituation" />
    					<xsd:enumeration value="DestroySituation" />
    					<xsd:enumeration value="ReportSituation" />
    					<xsd:enumeration value="AvailableSituation" />
    					<xsd:enumeration value="OtherSituation" />
    					<xsd:maxLength value="64" />
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:complexType name="SituationType" abstract="true">
    		<xsd:attribute name="reasoningScope" use="required">
    			<xsd:simpleType>
    				<xsd:restriction base="xsd:string">
    					<xsd:maxLength value="64"></xsd:maxLength>
    				</xsd:restriction>
    			</xsd:simpleType>
    		</xsd:attribute>
    	</xsd:complexType>
    	<xsd:complexType name="StartSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="situationQualifier" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="StopSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="situationQualifier" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="ConnectSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="situationDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="RequestSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="situationQualifier" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="ConfigureSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="AvailableSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="operationDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="availabilityDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    				<xsd:attribute name="processingDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="ReportSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="reportCategory" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="CreateSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="DestroySituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="successDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="FeatureSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="featureDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="DependencySituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:attribute name="dependencyDisposition" use="required">
    					<xsd:simpleType>
    						<xsd:restriction base="xsd:string">
    							<xsd:maxLength value="64"></xsd:maxLength>
    						</xsd:restriction>
    					</xsd:simpleType>
    				</xsd:attribute>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
    	<xsd:complexType name="OtherSituation">
    		<xsd:complexContent>
    			<xsd:extension base="cbe:SituationType">
    				<xsd:sequence>
    <xsd:any namespace="##any" minOccurs="1" maxOccurs="1" processContents="skip" />
    				</xsd:sequence>
    			</xsd:extension>
    		</xsd:complexContent>
    	</xsd:complexType>
     
    </xsd:schema>
     
    

    Sample Common Base Element XML

    This section shows two examples of Common Base Element XML.

    Example 1

    This sample shows how two Common Base Elements may be associated by value. Note in the first event below the value of the resolvedEvents attribute in the associateEvents element and how it matches the globalInstanceId attribute of the top-level CommonBaseEvent element in the second Common Base Element. Also note how an associationEngine is specified using the associationEngineInfo subelement. By matching these values and specifying a suitable association engine, it can be shown that these two events are related.

    <?xml version="1.0" encoding="UTF-8"?>
    <CommonBaseEvents xmlns="http://www.ibm.com/AC/commonbaseevent1_0_1" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.ibm.com/AC/commonbaseevent1_0_1 commonbaseevent1_0_1.xsd ">
    <CommonBaseEvent creationTime="2001-12-31T12:00:00" elapsedTime="0" extensionName="Name" 
    globalInstanceId="i0000000000000000000000000000040" localInstanceId="" msg="" priority="0" 
    repeatCount="0" sequenceNumber="0" severity="0" version="">
       <contextDataElements name="myContext" type="String">
    	 <contextValue>contextValue</contextValue> 
       </contextDataElements>
    	<extendedDataElements name="" type="noValue">
    	<values>valuesvalues</values>
    	<children name="" type="noValue"> 
    	 <values>valuesvalues</values>
    	</children>
     	</extendedDataElements>
    	<associatedEvents resolvedEvents="i0000000000000000000000000000040">
    	  <associationEngineInfo id="i0000000000000000000000000000044" name="MyCorrelationEngine" 
    		type="Correlate"/>
    	</associatedEvents>
    	<reporterComponentId application="" componentType="" component="" componentIdType="" 
    	executionEnvironment="" instanceId="" location="" locationType="Name" processId="" subComponent="" 
    	threadId=""/>
    	<sourceComponentId application="" componentType="" component="" componentIdType="" 
    	executionEnvironment="" instanceId="" location="" locationType="Name" processId="" subComponent="" 
    	threadId=""/>
    	<msgDataElement msgLocale="EN">
    	  	<msgCatalogTokens value=""/>
    		<msgId>msgIdmsgId</msgId>
    		<msgIdType>NamemsgIdType</Name>
    		<msgCatalogId>msgCatalogIdmsgCatalogId</msgCatalogId>
    		<msgCatalogType>msgCatalogTypemsgCatalogType</msgCatalogType>
    		<msgCatalog>msgCatalogmsgCatalog</msgCatalog>
    	</msgDataElement>
    	<situation categoryName="StartSituation">
    			<situationType reasoningScope="EXTERNAL" successDisposition="SUCCESSFUL" 
    			situationQualifier="START COMPLETED" xsi:type="StartSituation" />
    			</situation>
    	<a:a xmlns:a="http://bar" />
    </CommonBaseEvent>
    </CommonBaseEvents>
    

    Example 2

    This example illustrates how to associate two events by referencing the globalInstanceId of one event in another. However, in this sample, the association engine is specified separately from the actual Common Base Events.

    <?xml version="1.0" encoding="UTF-8"?>
    <CommonBaseEvents xmlns="http://www.ibm.com/AC/commonbaseevent1_0_1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.ibm.com/AC/commonbaseevent1_0_1 commonbaseevent1_0_1.xsd ">
    <associationEngine id="i0000000000000000000000000000044" name="MyCorrelationEngine" type="Correlate"/>
    <CommonBaseEvent creationTime="2001-12-31T12:00:00" elapsedTime="0" extensionName="Name" 
    globalInstanceId="i0000000000000000000000000000040" localInstanceId="" msg="" priority="0" 
    repeatCount="0" sequenceNumber="0" severity="0" version="">
    	<contextDataElements name="" type="">
    	<contextValue>contextValuecontextValue</contextValue>
    </contextDataElements>
    <extendedDataElements name="" type="noValue">
    	<values>values</values>
    	<children name="" type="noValue">
    		<values>values></values>
    	</children>
    </extendedDataElements>
    <associatedEvents resolvedEvents="i0000000000000000000000000000040">
    	<associationEngine>i0000000000000000000000000000044</associationEngine>
    </associatedEvents>
    <reporterComponentId application="" componentType="" component="" componentIdType="" 
    executionEnvironment=""<instanceId="" location="" locationType="Name" processId="" subComponent="" 
    threadId=""/>
    sourceComponentId application="" componentType="" component="" componentIdType="" 
    executionEnvironment="" instanceId="" location="" locationType="Name" processId="" subComponent="" 
    threadId=""/>
    <msgDataElement msgLocale="EN">
    	<msgCatalogTokens value=""/>
    	<msgId>msgId</msgId>
    	<msgIdType>Name</msgIdType>
    	<msgCatalogId>msgCatalogId</msgCatalogId>
    	<msgCatalogType>msgCatalogType</msgCatalogType>
    	<msgCatalog>msgCatalog</msgCatalog>
    </msgDataElement>
    <situation categoryName="StartSituation">
    		<situationType reasoningScope="EXTERNAL" successDisposition="SUCCESSFUL" 
    		situationQualifier="START COMPLETED" xsi:type="StartSituation"/>
    		</situation>
    	<a:a xmlns:a="html://bar" />
    </CommonBaseEvent>
    </CommonBaseEvents>
    

    Common Base Event class hierarchy

    Figure 7 depicts the CommonBaseEvent schema using Unified Modeling Language (UML) notation. This graphical language has been used to simplify the visualization of the CommonBaseEvent schema. For detailed descriptions of the CommonBaseEvent and its properties, see CommonBaseEvent description.

    Figure 7. The CommonBaseEvent schema

    The CommonBaseEvent schema in flowchart form

    Legend

    Rectangle box: Represents a class, which is a group of methods and properties that have similar attributes and behavior. Class name is specified on top part of the box followed by the attributes and their type. Operations are typically shown in the bottom portion of the box but are not specified here.

    Straight line: Indicates an association or relationship between classes. The direction is indicated by an arrow head (>).

    Solid diamond: Depicts a composite aggregation (by-value) or "has" relationship. The diamond is placed on the target end of the aggregation next to the target class, indicating that a class is embedded within another class. Cardinality, the number of objects, is indicated by numbers on either end of the association line.

    Hollow diamond: Depicts an aggregate association relationship (by-reference) between two classes to show that each instance of one class has a pointer or reference within it to an instance of another class. The hollow diamond is placed on the target end of the aggregation next to the target class.

    Common Base Event mappings

    This section details Common Base Event mappings.

    Mapping Java logging levels to severity

    The tables below show the various terms used in logs and their severity.

    Table 23. Java 1.4

    Logging level Severity
    Severe Critical
    Warning Warning
    Info Information
    Config Information
    Fine Information
    Finer Information
    Finest Information

    Table 24. Apache commons logging

    Logging level Severity
    Fatal Fatal
    Error Critical
    Warn Warning
    Info Information
    Debug Information
    Trace Information

    Table 25. JRAS tracing levels

    Logging level Severity
    Fatal Fatal
    Error Critical
    Warning Warning
    Info Information
    Audit Information
    Unknown Unknown
    Service Information

    Table 26. JRAS logging levels

    Logging level Severity
    Error Critical
    Err Critical
    Warning Warning
    Warn Warning
    Information Information
    Info Information

    Component type namespace

    A component type is a well-defined name (syntax and semantics) that is used to characterize all instances of a given kind of component. This section provides enumeration of standardized values for component types that might be used by IBM products. The component type namespace is divided into several name spaces to facilitate delegation to various product groups. However, it is expected that the initial list of component types are globally unique to facilitate their use without a qualifier.


    Appendix B. Getting help, service, and information

    If you need help, service, technical assistance, or just want more information about IBM products, you will find a wide variety of sources available from IBM to assist you.

    IBM maintains pages on the World Wide Web where you can get information about IBM products and services and find the latest technical information.

    If you need help, use the support forum on the developerWorks Web site at:

    www.ibm.com/developerworks/autonomic/


    Appendix C. Notices

    This publication was developed for products and services offered in the U.S.A.

    IBM(R) may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

    IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

    IBM Director of Licensing
    IBM Corporation
    North Castle Drive
    Armonk, NY 10504-1785
    U.S.A.

    INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

    This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

    Any references in this publication to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product, and use of those Web sites is at your own risk.

    IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.


    Trademarks

    The following are trademarks of International Business Machines Corporation in the United States, other countries, or both:


    AIX PS/2

    BladeCenter Redbooks

    Chipkill ServerProven

    the IBM logo TechConnect

    Lotus X-Architecture

    Predictive Failure Analysis xSeries

    Intel and Xeon are trademarks of Intel Corporation in the United States, other countries, or both.

    Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.

    UNIX is a registered trademark of The Open Group in the United States and other countries.

    Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

    Figure 8. Java logo

    Java logo

    Other company, product, or service names may be trademarks or service marks of others.


    Important notes

    Processor speeds indicate the internal clock speed of the microprocessor; other factors also affect application performance.

    CD-ROM drive speeds list the variable read rate. Actual speeds vary and are often less than the maximum possible.

    When referring to processor storage, real and virtual storage, or channel volume, KB stands for approximately 1000 bytes, MB stands for approximately 1 000 000 bytes, and GB stands for approximately 1 000 000 000 bytes.

    When referring to hard-disk-drive capacity or communications volume, MB stands for 1 000 000 bytes, and GB stands for 1 000 000 000 bytes. Total user-accessible capacity may vary depending on operating environments.

    Maximum internal hard-disk-drive capacities assume the replacement of any standard hard disk drives and population of all hard-disk-drive bays with the largest currently supported drives available from IBM.

    Maximum memory may require replacement of the standard memory with an optional memory module.

    IBM makes no representation or warranties regarding non-IBM products and services that are in the ServerProven(R) program, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. These products are offered and warranted solely by third parties.

    IBM makes no representations or warranties with respect to non-IBM products. Support (if any) for the non-IBM products is provided by the third party, not IBM.

    Some software may differ from its retail version (if available), and may not include user manuals or all program functionality.


    Index

    Numerics
    A B C D E F G H I J L M N O P R S T U V W X
    Numerics A B C D E F G H I J L M N O P R S T U V W X

    1
    RFC 2119, "Key words for use in RFCs to Indicate Requirement Levels," www.ietf.org/rfc/rfc2119.txt

    2
    W3C XML Schema Part 2: Datatypes, W3C Recommendation 02 May 2001, www.w3.org/TR/2001/REC-xmlschema-2-20010502/

    3
    W3C XML Schema Part 2: Datatypes, W3C Recommendation 02 May 2001, www.w3.org/TR/2001/REC-xmlschema-2-20010502/

    4
    See Grid Services Specification Draft 4, Global Grid Forum, www.gridforum.org/ogsi.wg