Overview.. 3

Introduction. 3

Getting Started. 3

Requirements. 3

GES Client API Reference. 4

GESConstants. 4

EventSenderHelper 5

Constructors. 5

EventSenderHelper 5

Methods. 5

configureSourceComponentValues. 5

createEvent 6

createAndSendEvent 7

sendEvent 8

EventAccessHelper 9

Constructors. 9

EventAccessHelper 9

Methods. 9

getEventByGlobalInstanceId. 9

getEventByLocalInstanceId. 10

getEvents. 10

getEvents. 11

Overview

This document explains in detail the functions that can be invoked using the Generic Event Service (GES) API.

Introduction

The Generic Event Service (GES) API provides access to the GES. This API is used to send and access events sent by various internal GSi Gov. services and external verticals. Using this API, the verticals can benefit from a common format and mechanism to send and retrieve events.

This GES API provides the following functions:

• Create events
• Send events to GES
• Access / Search GES events

Getting Started

To use the GES API, GES should be deployed and should be available on the remote port. In case of both GES and the client using GES are on the same server, port access should not be a problem. In case of different servers, than the remote port on the server which runs GES should be enabled for remote access by the client (this port will be different from the HTTP one).

Requirements

 The following jars will be required to use the GES API.

emf.common_2.2.1.v200702131851.jar

emf.ecore_2.2.2.v200702131851.jar

hlcbe101.jar

hlcore.jar

tlcore.jar

GenericEventServiceSubs.jar

Apart from the above jars, based on which application server GES is running the following additional client jars are required.

JBoss - jnpserver.jar, jbossall-client.jar

GES Client API Reference

The GES Client API has two classes, one for sending events and the other one for accessing/searching events. The API consists of two main classes, EventSenderHelper  (Package: com.comat.gsi.ges.api) for sending events and

EventAccessHelper  (Package: com.comat.gsi.ges.api) for accessing/searching events

For detailed information, refer to the Javadoc API documents provided with the distribution.

The API classes are used to invoke the operations provided Generic Event Service. Both the classes use RMI based communication, with the end-point being EJB’s. Both the API classes have constructors which enable in container / remote working w.r.t GES deployment.fs

GESConstants

This class provide the generic constants that are used by the GES API while sending events. A set of constants each are provided for category, qualifier and disposition.

The following set of values is supported:

Category/Situation

This property categorizes the situation that caused the event. The supported situation/ category are as follows:

StartSituation                - Start up of a process

StopSituation                - Stop / shutdown of a process

RequestSituation           - Situation that a component uses to identify completion status

CreateSituation;            - Component creating entities

DestroySituation           - Component deleting / removing entities

ConfigureSituation        - situation deals with components identifying their configuration

ReportSituation             - deals with situations reported from component

OtherSituation              - other situations that the one described above

Qualifier

This is the also known as the reasoning scope and specifies the scope of the situation w.r.t the component. There are two possible values:

INTERNAL

EXTERNAL

Disposition

This attribute specifies the success disposition of an operation of a situation.

The following the values uses typically:

SUCCESSFUL

UN SUCCESSFUL

EventSenderHelper

This class represents the client API for sending events to Generic Event Service. Helps to get the Event Factory and send CBE events to the Generic Event Service.

Constructors

EventSenderHelper Creation

The instance of the EventSenderHelper needs to be created to invoke the GES Client API.

EventSenderHelper

Creates a new instance of EventSenderHelper. Use this to connect to the local / in-container GES (case where the GES and the client are running in the same application server).

Parameters:

Sample Usage:

EventSenderHelper eventSenderHelper = new EventSenderHelper();

EventSenderHelper (Hashtable contextEnv)

Creates a new instance of EventSenderHelper with the passed context env

Parameters:

contextEnv – Context parameters to connect to the remote server GES

Sample Usage:

Hashtable env = new Hashtable();        env.put("java.naming.factory.initial","org.jnp.interfaces.NamingContextFactory");

env.put("java.naming.provider.url","127.0.0.1:1099");

env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces");

EventSenderHelper eventSenderHelper = new EventSenderHelper(env);

Methods

configureSourceComponentValues

Configures the Source Component identification attributes. This should be done once and the API automatically populates for all events.

Signature:

void configureSourceComponentValues(String application, String 

               component, String componentType, String subComponent)

Parameters:

application – the applicant name

component   - the component name

componentType – the component type, mostly “Application”

subComponent.  – the sub-component type

Returns:

Throws:

Sample Usage:

eventSenderHelper.configureSourceComponentValues("Generic Services Configurator", "IdentityManagement","Application", "Identity Manager");

configureSourceComponentValues

Configures the Source Component identification attributes with default component type "Application". This should be done once and the API automatically populates for all events.

Signature:

void configureSourceComponentValues(String application, String 

               component, String subComponent)

Parameters:

application – the applicant name

component   - the component name

subComponent.  – the sub-component name

Returns:

Throws:

Sample Usage:

eventSenderHelper.configureSourceComponentValues("Generic Services Configurator", "IdentityManagement", "Identity Manager");

createEvent

Create the generic event with passed event name , message and situation attributes.

In this case, the Qualifier defaults to “INTERNAL” and disposition to “SUCCESSFUL”.

Note: There are four variants of this method. Use JavaDoc to see the specific method usage.

Signature:

CommonBaseEvent createEvent(String eventName, String msg, long  

            occuredAt,String categoryName,Map extendedAttrs)

Parameters:

eventName – the event name

msg   - the event message

occuredAt – event occurred time in ms

categoryName – the event category name

extendedAttrs.  – key-value pair of extended attributes (type - string)

Returns:

CommonBaseEvent – the CBE event

Throws:

Sample Usage:

Map extendedAtrs = new HashMap();

extendedAtrs.put("Name","DistSrvIdentityPolicy");

CommonBaseEvent cbe = eventSenderHelper.createEvent("CreatePolicy", 

       “Created Policy with name DistSrvIdentityPolicy successfully.",   System.currentTimeMillis(),”ConfigureSituation", extendedAtrs);

createAndSendEvent

Create and sends the generic event with passed event name, message and situation attributes. In this case, the Qualifier defaults to “INTERNAL” and disposition to “SUCCESSFUL”.

Note: There are four variants of this method. Use JavaDoc to see the specific method usage.

Signature:

int createAndSendEvent(String eventName, String msg, long  

            occuredAt,String categoryName,Map extendedAttrs)

Parameters:

eventName – the event name

msg   - the event message

occuredAt – event occurred time in ms

categoryName – the event category name

extendedAttrs.  – key-value pair of extended attributes (type - string)

Returns:

int - status - 1 for success and -1 for failure

Throws:

Sample Usage:

Map extendedAtrs = new HashMap();

extendedAtrs.put("Name","DistSrvIdentityPolicy");

int status = eventSenderHelper.createAndSendEvent("CreatePolicy", 

       “Created Policy with name DistSrvIdentityPolicy successfully.",   System.currentTimeMillis(),”ConfigureSituation", extendedAtrs);

sendEvent

Sends the specified event to Generic Event Service

Signature:

int sendEvent(CommonBaseEvent genericEvent)

Parameters:

genericEvent – the CBE event

Returns:

int - status - 1 for success and -1 for failure

Throws:

CompletionException, ValidationException

Sample Usage:

CommonBaseEvent cbe = eventSenderHelper.createEvent("CreatePolicy", 

       “Created Policy with name DistSrvIdentityPolicy successfully.",   System.currentTimeMillis(),”ConfigureSituation", extendedAtrs);

try {

   int status = eventSenderHelper.sendEvent(cbe);

}catch(CompletionException ce) { //Source component values not provided

}

catch(ValidationException ce) { //Values not in range / invalid

}

EventAccessHelper

This class provides methods to access GES events for id and query based searching

Constructors

EventAccessHelperCreation

The instance of the EventAccessHelper needs to be created to invoke the GES Client API.

EventAccessHelper

Creates a new instance of EventAccessHelper. Use this to connect to the local / in-container GES (case where the GES and the client are running in the same application server).

Parameters:

Sample Usage:

EventAccessHelper eventAccessHelper = new EventAccessHelper ();

EventAccessHelper (Hashtable contextEnv)

Creates a new instance of EventAccessHelper with the passed context env

Parameters:

contextEnv – Context parameters to connect to the remote server GES

Sample Usage:

Hashtable env = new Hashtable();        env.put("java.naming.factory.initial","org.jnp.interfaces.NamingContextFactory");

env.put("java.naming.provider.url","127.0.0.1:1099");

env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces");

EventAccessHelper eventAccessHelper = new EventAccessHelper (env);

Methods

getEventByGlobalInstanceId

Get the CBE event for the specified global instance id

Signature:

CommonBaseEvent getEventByGlobalInstanceId(String globalInstanceId)

Parameters:

globalInstanceId – the event global instance id

Returns:

            CommonBaseEvent – if a matching event is found, else null

Throws:

Sample Usage:

CommonBaseEvent cbe = eventAccessHelper.getEventByGlobalInstanceId(“ASD12768hjjhsdf”);

getEventByLocalInstanceId

Get the CBE event for the specified local instance id. As of the current version, this is not  being used.

Signature:

CommonBaseEvent getEventByLocalInstanceId(String localInstanceId)

Parameters:

localInstanceId – the event local instance id

Returns:

            CommonBaseEvent – if a matching event is found, else null

Throws:

Sample Usage:

CommonBaseEvent cbe = eventAccessHelper.getEventByLocalInstanceId(“ASD12768hjjhsdf”);

getEvents

Get events based on the specified criteria. Use this to query by all events or by a specific event name.

Signature:

CommonBaseEvent[] getEvents(String eventName, String application, 

     String compName, String subCompName, long fromDate, long toDate)

Parameters:

eventName– the event name or “%” for all events

application – the applicant name

component   - the component name

subComponent  – the sub-component name

fromDate – event occurred from time in ms

toDate – event occurred to time in ms

Returns:

            CommonBaseEvent[] – an array of CBE events

Throws:

Sample Usage:

EventAccessHelper eventAccessHelper = new EventAccessHelper(env);     

String eventName = new String(“USER_CREATED”);

//String eventName = new String(“%”); // in case of all events

CommonBaseEvent[] events = eventAccessHelper.getEvents(eventName,”IDM”,”Identity”,”AccessManager”,-1,-1);

getEvents

Get events based on the specified search criteria including a list of event names, application type defaults to "Application"

Signature:

CommonBaseEvent[] getEvents(String eventNames[], String application, 

     String compName, String subCompName, long fromDate, long toDate)

Parameters:

eventNames – the list of event names within the same application and component.

application – the applicant name

component   - the component name

subComponent  – the sub-component name

fromDate – event occurred from time in ms

toDate – event occurred to time in ms

Returns:

            CommonBaseEvent[] – an array of CBE events

Throws:

Sample Usage:

EventAccessHelper eventAccessHelper = new EventAccessHelper(env);        

String eventNames[] = new String[] {“USER_CREATED”, “USER_MODIFIED”};

CommonBaseEvent[] events = eventAccessHelper.getEvents(eventNames,”IDM”,”Identity”,”AccessManager”,-1,-1);