IBM WebSphere Application ServerTM
Release 8

com.ibm.events.access
Interface EventAccess

All Superinterfaces:
javax.ejb.EJBObject, java.rmi.Remote

public interface EventAccess
extends javax.ejb.EJBObject

Remote interface for the event access enterprise bean.

This interface uses the following security roles:

Since:
5.1.0
Version:
1.2 10/6/13

Field Summary
static int DEFAULT_PURGE_TRANSACTION_SIZE
          Default transaction size to use when purging events.
 
Method Summary
 boolean eventExists(java.lang.String eventGroup, java.lang.String eventSelector)
          Determines if events exist that belong to the specified event group.
 ComponentMetaData getDataStoreMetaData()
          Returns the component metadata of the data store enterprise bean.
 ComponentMetaData getMetaData()
          Returns the component metadata of the event access enterprise bean.
 int purgeEvents(java.lang.String eventGroup, java.lang.String eventSelector, int transactionSize)
          Removes a group of events from the data store.
 org.eclipse.hyades.logging.events.cbe.CommonBaseEvent queryEventByGlobalInstanceId(java.lang.String globalInstanceId)
          Retrieves an event by the global Instance ID.
 org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByAssociation(java.lang.String associationType, java.lang.String globalInstanceId)
          Retrieves events that are related to the specified global Instance ID.
 org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByEventGroup(java.lang.String eventGroup, java.lang.String eventSelector, boolean ascendingOrder)
          Retrieves events that belong to the specified event group.
 org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByEventGroup(java.lang.String eventGroup, java.lang.String eventSelector, boolean ascendingOrder, int maximumNumber)
          Retrieves events that belong to the specified event group.
 void updateEvents(EventChangeRequest[] eventChangeRequests)
          Updates events that are persisted in the event infrastructure repository.
 
Methods inherited from interface javax.ejb.EJBObject
getEJBHome, getHandle, getPrimaryKey, isIdentical, remove
 

Field Detail

DEFAULT_PURGE_TRANSACTION_SIZE

static final int DEFAULT_PURGE_TRANSACTION_SIZE
Default transaction size to use when purging events.

See Also:
Constant Field Values
Method Detail

getDataStoreMetaData

ComponentMetaData getDataStoreMetaData()
                                       throws EventsException,
                                              java.rmi.RemoteException
Returns the component metadata of the data store enterprise bean.

Returns:
The component metadata for the data store.
Throws:
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean.

getMetaData

ComponentMetaData getMetaData()
                              throws java.rmi.RemoteException
Returns the component metadata of the event access enterprise bean.

Returns:
The component metadata for the event access enterprise bean.
Throws:
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean.

eventExists

boolean eventExists(java.lang.String eventGroup,
                    java.lang.String eventSelector)
                    throws EventsException,
                           java.rmi.RemoteException
Determines if events exist that belong to the specified event group.

The eventConsumer, eventUpdater, or the eventAdministrator security role is required for this method.

Parameters:
eventGroup - The name of the event group to query. This value cannot be null.
eventSelector - An additional XPath expression that is appended to the event group selector. This value can be null if an additional event selector is not needed. Must be in the form CommonBaseEvent[]. For example: CommonBaseEvent[@sequenceNumber >1].
Returns:
true if an event exists that matches the event group and the event selector. false otherwise.
Throws:
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventGroupNotDefinedException - If the passed event group name is not defined.
com.ibm.events.util.xpath.InvalidEventSelectorException - If either the passed event selector or the event group selector is not valid.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

purgeEvents

int purgeEvents(java.lang.String eventGroup,
                java.lang.String eventSelector,
                int transactionSize)
                throws EventsException,
                       java.rmi.RemoteException
Removes a group of events from the data store.

If both the eventGroupSelector and the eventSelector parameters are null, then all events are purged.

The eventAdministrator security role is required for this method.

Parameters:
eventGroup - The name of the event group that the events being purged belong to. This can be null if a specific event group is not being used.
eventSelector - An additional event filter that is used to select the events that will be purged from the database. This value can be null if an additional selector is not needed. Must be in the form CommonBaseEvent[]. For example: CommonBaseEvent[@sequenceNumber >1].
transactionSize - The number of events to delete in a single database transaction. This value must be greater than 0.
Returns:
The number of events that were purged
Throws:
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventGroupNotDefinedException - If the passed event group name is not defined.
com.ibm.events.util.xpath.InvalidEventSelectorException - If either the passed event selector or the event group selector is not valid.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

queryEventByGlobalInstanceId

org.eclipse.hyades.logging.events.cbe.CommonBaseEvent queryEventByGlobalInstanceId(java.lang.String globalInstanceId)
                                                                                   throws EventsException,
                                                                                          java.rmi.RemoteException
Retrieves an event by the global Instance ID.

The eventConsumer, eventUpdater, or the eventAdministrator security role is required for this method.

Parameters:
globalInstanceId - The global Instance ID of the event that is to be returned. This value cannot be null.
Returns:
An event instance or null if there is not an event that contains the specified global Instance ID.
Throws:
IllegalArgmentException - If the global instance id parameter is null.
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

queryEventsByAssociation

org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByAssociation(java.lang.String associationType,
                                                                                 java.lang.String globalInstanceId)
                                                                                 throws EventsException,
                                                                                        java.rmi.RemoteException
Retrieves events that are related to the specified global Instance ID.

The eventConsumer, eventUpdater, or the eventAdministrator security role is required for this method.

Parameters:
associationType - The type of the association. This value cannot be null.
globalInstanceId - The global Instance ID of the event to which other events are associated. This value cannot be null.
Returns:
An array of all events that match the query. If no events match the query, an empty array is returned.
Throws:
IllegalArgmentException - If the global instance id parameter or associationType parameters are null
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

queryEventsByEventGroup

org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByEventGroup(java.lang.String eventGroup,
                                                                                java.lang.String eventSelector,
                                                                                boolean ascendingOrder)
                                                                                throws EventsException,
                                                                                       java.rmi.RemoteException
Retrieves events that belong to the specified event group.

The caller passes the event group, an event selector and specifies whether the events are arranged in ascending or descending order according to the creation time of the event.

The eventConsumer, eventUpdater, or the eventAdministrator security role is required for this method.

Parameters:
eventGroup - The name of the event group to query. This value cannot be null.
eventSelector - An additional XPath expression that is appended to the event group selector. This value can be null if an additional event selector is not needed.
ascendingOrder - Whether events are ordered in ascending or descending order according to creation time.
Returns:
An array of all events that match the query. If no events match the query, an empty array is returned.
Throws:
IllegalArgmentException - If the eventGroup parameter is null.
IllegalArgmentException - If the maximumNumber parameter is less than 1.
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventGroupNotDefinedException - If the passed event group name is not defined.
com.ibm.events.util.xpath.InvalidEventSelectorException - If either the passed event selector or the event group selector is not valid.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

queryEventsByEventGroup

org.eclipse.hyades.logging.events.cbe.CommonBaseEvent[] queryEventsByEventGroup(java.lang.String eventGroup,
                                                                                java.lang.String eventSelector,
                                                                                boolean ascendingOrder,
                                                                                int maximumNumber)
                                                                                throws EventsException,
                                                                                       java.rmi.RemoteException
Retrieves events that belong to the specified event group.

The caller passes the event group, an additional event selector, the number of events to return and specifies whether the events are arranged in ascending or descending order according to the creation time of the event.

The eventConsumer, eventUpdater, or the eventAdministrator security role is required for this method.

Parameters:
eventGroup - The name of the event group to query. This value cannot be null.
eventSelector - An additional XPath expression that is appended to the event group selector. This value can be null if an additional event selector is not needed.
ascendingOrder - Whether events are ordered in ascending or descending order according to creation time.
maximumNumber - The maximum number of events to be returned from the event query. Must be at least 1
Returns:
An array of all events that match the query. If no events match the query, an empty array is returned.
Throws:
IllegalArgmentException - If the eventGroup parameter is null.
IllegalArgmentException - If the maximumNumber parameter is less than 1.
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If the configured data store cannot be connected to.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If the event service is configured to not use persistence.
EventGroupNotDefinedException - If the passed event group name is not defined.
com.ibm.events.util.xpath.InvalidEventSelectorException - If either the passed event selector or the event group selector is not valid.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.

updateEvents

void updateEvents(EventChangeRequest[] eventChangeRequests)
                  throws EventsException,
                         java.rmi.RemoteException
Updates events that are persisted in the event infrastructure repository.

If any of the change requests fail then the current transaction will be marked for roll back.

The eventUpdater or the eventAdministrator security role is required for this method.

Parameters:
eventChangeRequests - An array of change requests that can span multiple events.
Throws:
com.ibm.events.datastore.DataStoreException - If the data store fails to perform the requested action.
DataStoreConnectionFailureException - If a connection to the configured data store cannot be made.
CbeVersionNotSupportedException - If the data store does not support the same version of the event that the event service supports.
DataStoreNotEnabledException - If event service is not configured to use persistence.
EventDoesNotExistException - If event specified in one of the change requests does not exist.
SeverityAlreadySetException - If one of the change requests tries to modify the value of severity. It is only valid to set an unset severity.
ExtendedDataElementUpdateException - If the parent extended data element does not exist
EventUpdatesNotSupportedException - If the configured data store does not support event updates.
EventDistributionException - If event distribution fails to publish the event notifications to any event groups.
EventsException - If the Common Event Infrastructure fails due to an error.
java.rmi.RemoteException - If an error occurs when accessing the event access enterprise bean or if there are any errors in the parameters passed to the enterprise bean.
java.lang.IllegalArgumentException - If any of the required parameters are not specified.

IBM WebSphere Application ServerTM
Release 8