Title:              Common Base Event Factory Design

Author(s):    Paul Slauenwhite (paules@ca.ibm.com)

                        Richard Duggan (rduggan@ca.ibm.com)

Version:        March 24, 2005

Since:            March 31, 2004

 

Contents:

 

  1. Introduction
  2. Interface Design
  3. Reference Implementation
  4. Evolvability
  5. Documentation
  6. Sample
  7. References

 

Introduction:

           

This document details the design of the factory for both Common Base Event v1.0.1 implementations in the Test and Performance Tools Platform (TPTP) project.  The Eclipse Modeling Framework (EMF) Common Base Event implementation is shipped with TPTP (formally Hyades) v1.3.0 and above.  The non-EMF Common Base Event implementation is shipped with TPTP v4.0.0 and above.  This document provides the design of factory interfaces and a simple programming model.  However, a concrete type of factory implementation using textual Common Base Event XML properties files is provided as a reference implementation.  Consult the Evolvability section of this document to explore additional implementations. 

 

In TPTP (formally Hyades) v1.3.0 and above, the EMF-based Common Base Event implementation in the org.eclipse.hyades.loggging.core plug-in (e.g. hlcbe101.jar) contains the implementation interfaces (org.eclipse.hyades.loggging.events.cbe package) and implementation classes (org.eclipse.hyades.loggging.events.cbe.impl package) of the factory.  In TPTP v4.0.0 and above, the EMF-based Common Base Event implementation in the org.eclipse.hyades.loggging.core plug-in (e.g. tlcbe101.jar) contains the implementation interfaces (org.eclipse.tptp.loggging.events.cbe package) and implementation classes (org.eclipse.tptp.loggging.events.cbe.impl package) of the factory.

 

It is important to note that the Common Base Event implementations and their factories do not infer anything about the event’s consumer(s).  For instance, application code may log or consume events in any manner applicable to the intent of the application.  As long as the consuming logging facility or application code accepts java.lang.Object parameters, the event may be used to capture situational data.  As such, the Common Base Event implementations provide event creation and configuration functionality and does not define any consumer preconditions.         

 

 

Interface Design:

 

The design of the Common Base Event factory is composed of a layered architecture with four layers or levels of abstraction:

           

  1. Event Factory Context
  2. Event Factory Home
  3. Event Factory
  4. Event

 

The first layer or highest level of abstraction is the Event Factory Context.  This level provides a look-up service locating Event Factory Homes.  The look-up service locates and returns an Event Factory Home based on a preferred type (e.g. fully qualified package and class name).  The preferred type may be set programmatically in the Event Factory Context.  The benefit of this service is that application code does not have to import or invoke typed Event Factory Homes directly.  This look-up service is optional and is not required to create an Event Factory Home.  The implementation of this class is a singleton design pattern.  Instances are retrieved by invoking the static getEventFactoryContext() API.  Figure 1 illustrates the design of the Event Factory Context in the form of a class diagram. 

 


 

Figure 1: Event Factory Context Class Diagram

 

The second layer is the Event Factory Home.  This level provides Event Factory instantiation based on a unique factory name.  Event Factory Home implementations are tightly coupled with a type of configuration template used to populate a newly created Event.  Event Factory instances are maintained by the associated Event Factory Home based on their unique name.  For example, when application code requests a named Event Factory, the newly created Event Factory instance is returned and persisted for future requests for that named Event Factory.  An abstract Event Factory Home class provides the implementation for the APIs in the Event Factory Home interface.  Implementers extend the abstract Event Factory Home class and implement the createContentHandler() and resolveContentHandler() APIs to create a typed Content Handler based on the type of the Event Factory Home implementation.  Figure 2 illustrates the design of the Event Factory Home in the form of a class diagram. 

 

 

 

Figure 2: Event Factory Home Class Diagram

 

 

The abstract Event Factory Home class is responsible for the following tasks:

 

  • Creating new Event Factory instances.
  • Persisting Event Factory instances in an internal data structure.
  • Retrieving persisted Event Factory instances.
  • Refreshing the configuration template (e.g. properties file) data. 

 

Event Factory Home implementations are responsible for the following tasks:

 

  • Retrieving the configuration template (e.g. properties file).
  • Creating a Content Handler based on the data in the configuration template and set the Content Handler on the returned Event Factory.

 

The third layer is the Event Factory.  This level provides a factory for creating Events and pre-populating Event properties with a predefined configuration template.  Once an event has been created and populated by the Event Factory using the predefined configuration template, application code may retrieve and set any event property.  All event properties set by the application code have priority over all properties specified in the predefined configuration template.  Event Factory implementations are tightly coupled with the instance of a configuration template used to populate a newly created Event.  For instance, each named Event Factory instance is created, the configuration template (e.g. properties file) associated with that Event Factory instance remains the only configuration template used for the lifecycle of the Event Factory.  Factory instances can only be retrieved from its associated Event Factory Home.  Event Factory instances are retrieved and maintained based on unique names.  Event Factory names are hierarchal represented using the standard Java dot-delimited name-space naming conventions.  Figure 3 illustrates the design of the Event Factory in the form of a class diagram. 

 

 

Figure 3: Event Factory Class Diagram

 

This Event Factory provides a mechanism by which instantiated Events may be populated using a predefined configuration template at either creation time or in the future by the application code.  The physical configuration template is resolved by the Event Factory Home at factory initialization and/or factory update and associated with the Event Factory instance.  The in-memory realization of the   physical configuration template is a Content Handler.  At factory initialization and/or factory update, the Event Factory Home creates an instance of a specialized type of Content Handler called a Template Content Handler based on the physical configuration template.  The Event Factory Home assigns the Template Content Handler instance to the Event Factory.  Template Content Handler instances maintain an instance to a ‘template’ Event which is the in-memory realization of the physical configuration template.  Events created by the Event Factory are assigned a reference to the Event Factory’s Template Content Handler instance.  As such, application code may invoke the Event’s complete() API to merge the configuration template data from the Template Content Handler into the Event.  Once an Event have be ‘completed’, invoking the complete() API has no effect.  Only the first invocation of the Event’s complete() API after its Content Handler has been set cause the completion process to execute.  The precedence rules for merging configuration template data from the Template Content Handler into the Event are as follows:

 

  • String and primitive property values in the Event are considered 'golden' when the same property is set in the Template Content Handler’s 'template event'.
  • List property values in the Template Content Handler’s 'template event' are concatenated to the associated list property in the Event.
  • Complex (e.g. objects excluding strings) property values in the Event are internally compared to the associated Template Content Handler’s 'template event' property using the above rules.

  

The default behavior of the Event Factory is to delegate the responsibility of the invoking the Event’s complete() API to the application code.  Application code may query an Event at any point in time to determine if the complete() API has been invoked by invoking the isComplete() API.  There is a performance benefit to this default behavior in that Events that are never consumed are never ‘completed’.  Conversely, this default behavior may be problematic when an ‘uncompleted’ Event is forwarded to a consumer unaware of Events and/or Event completion.  Furthermore, problems may arise when Events are transported in containers unaware of Event completion which may attempt to map Event fields to container fields on an ‘uncompleted’ Event.  To circumvent these problems, the Event Factory may be configured to automatically invoke the Event’s complete() API when a new Event is created by the Event Factory by setting the completeEvent flag (e.g. setCompleteEvent()).  Application code may query the Event Factory at any time to determine is the completeEvent flag is turned on by invoking the Event Factory’s getCompleteEvent() API.  Note, if invoking the Event’s complete() by the Event Factory causes a CompletionException to be thrown, the exception is ignored and ‘uncompleted’ Event is returned.  Figure 4 illustrates the design of the Content Handler and the Template Content Handler in the form of a class diagram. 

 

 

Figure 4: Content Handler Class Diagram

 

 

The fourth layer or lowest level of abstraction is the Event.  This level is realized by the Common Base Event implementation in TPTP.  Once created and populated with the configuration template data, application code may change any property on the event to best represent the event’s situation.  For instance, if the configured event contains a sourceComponetId inferring that the application code is the source of the event and it is in fact the reporter of the event, the application can retrieve the sourceComponetId from the configured event and set the retrieved value as the reporterComponetId.  Note, the application code must invoke the complete() API before attempting to retrieve any event properties.  Figure 5 illustrates the design of the Event in the form of a class diagram. 

 

 

Figure 5: Content Handler Class Diagram

 

Reference Implementation:

 

The TPTP Project has provided a reference implementation of the Event Factory Home that configures Events with properties from a configuration template in the form of a template Event XML file.  The Event Factory Home reference implementation (EventXMLFileEventFactoryHomeImpl) provides a starting point for application developers to further extend Event Factory Home architecture for application-specific purposes and to provide a useful implementation based on template Event XML files.  Figure 6 illustrates the design of the Event Factory Home reference implementation in the form of a class diagram. 

 

 

 

Figure 6: Event Factory Home Reference Implementation Class Diagram

 

The Event Factory Home implementation consumes a configuration template in the form of a template Event XML file.  This template Event XML file is a well-formed XML document conforming to a predefined XML schema (e.g. templateEvent.xsd).  XSD Sample 1 illustrates the templateEvent.xsd which all template Event XML files must conform.

 


XSD Sample 1: Template Event Document Schema (templateEvent.xsd)

 

The format of the template Event XML file as enforced by the templateEvent.xsd schema consists of a root element (e.g. TemplateEvent) with an attribute (e.g. version) specifying the version of the Event specification.  The root element contains only one child element (e.g. CommonBaseEvent) which consists of a well-formed Event XML fragment.  The structure of the CommonBaseEvent element follows the Event schema specific to the root element’s version attribute.  This CommonBaseEvent element must follow the Event schema specific to the root element’s version attribute without the restrictions on required properties.

 

The naming convention used for the template Event XML file is:

 

<factory name>.event.xml

  

            where <factory name> is the unique dot-delimited name of the factory.

 

For example, the template Event XML file for the com.company.sample factory would be named com.company.sample.event.xml.  The template Event XML file must be available using the following search order:

 

1.       Event Factory’s class loader.

2.       System class loader.

3.       Current thread’s context class loader. 

           

Configuration templates are located based on the hierarchal factory name, starting from the full factory name (e.g. all name-space segments) and iterating its ancestors to the highest ancestor (e.g. first name-space segment).  For example, the com.company.sample factory name would cause the Event Factory Home to attempt to locate the configuration template named com.company.sample.  If this configuration template cannot be located, the Event Factory Home would attempt to locate the configuration template named com.company, and so on all the way to the configuration template named com.  

 

Evolvability:

 

The reference implementation of this factory design provides an Event Factory implementation using textual Common Base Event XML properties files to configure generate Events.  Other possible implementations include:

 

  1. JNDI look-up to an implementation of the Content Hander interface.

 

  1. Concrete implementations of the Content Hander interface.

 

  1. Application extensions to the Content Handler interface and Factory Home abstract class.

 

 

Documentation:

 

The documentation for the Common Base Event factory implementation consists of this design document as well as the Canonical Situation Data Format: Common Base Event v1.0.1 API Documentation  (see References).

 

 

Sample:

 

Consult the Hyades EMF Common Base Events v.1.0.1 Sample (File >> New >> Example… >> Hyades Logging >> Hyades EMF Common Base Events v.1.0.1 Sample) for an illustrative sample of how to instrument applications using the EMF Common Base Events v.1.0.1 implementation including its factory.

 

 

References:

 

[1] Canonical Situation Data Format: Common Base Event v1.0.1 Schema, http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/commonbaseevent1_0_1.xsd.

 

[2] Canonical Situation Data Format: Common Base Event v1.0.1 Specification, http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/CommonBaseEvent_SituationData_V1.0.1.pdf.

 

[3] Common Base Event v1.0.1 API Documentation, Help >> Help Contents >> Monitoring and Analyzing Performance >> Extended Test and Performance Tools Platform >> References.

 

[4] Eclipse Modeling Framework (EMF), http://www.eclipse.org/emf.

 

[5] TPTP Project, http://www.eclipse.org/TPTP.