EOEventCenter

Inherits from: Object

Package: com.webobjects.eocontrol

Class Description

EOEventCenter collects and manages EOEvents to allow you to measure the duration of operations in your applications. Measurements allow you to profile an application and optimize its execution time. For this, Enterprise Objects Framework and WebObjects instrument key portions of their code to measure the elapsed time of functions and methods.

For more information on the event logging feature and on instrumenting your own code for event logging, see the following sections:

Method Types

Registering event classes for logging
registerEventClass
registeredEventClasses
setRecordsEvents
recordsEventsForClass

Logging events
newEventOfClass
markAtomicEvent
markStartOfEvent
markEndOfEvent
cancelEvent

Accessing event centers
currentCenter
allCenters

Accessing events
allEventsForAllCenters
allEvents
eventsOfClassForAllCenters
eventsOfClass
rootEventsForAllCenters
rootEvents
rootEventsByDuration

Resetting and suspending event logging
resetLoggingForAllCenters
resetLogging
suspendLogging
resumeLogging

Constructors

EOEventCenter

public EOEventCenter()

Description forthcoming.

Static Methods

allCenters

public static NSArray allCenters()

Returns all event centers. Typically used only for post-processing of events and statistics gathering. Note that there is one event center per thread.

allEventsForAllCenters

public static NSArray allEventsForAllCenters()

Returns an array of all the events logged in all the event centers. The events in the returned array are in no particular order.

See Also: allEvents

cancelEvent

public static void cancelEvent(EOEvent event)

Cancels the recording of an in-progress event. This method doesn't work with atomic events or with events that have already been ended with markEndOfEvent.

Generally you cancel an event when the operation being logged is aborted. For example, the ODBCAdaptorChannel cancels an "Open Channel" event if the openChannel method doesn't successfully open a connection to the database.

currentCenter

public static EOEventCenter currentCenter()

Returns the event center for the calling thread.

eventsOfClassForAllCenters

public static NSArray eventsOfClassForAllCenters( Class aClass, String type)

Returns an array of all events (from all the event centers) that are instances of aClass and whose type is type. Specifying null for the class returns events of any class. Similarly, specifying null for the type returns events of any type.

See Also: eventsOfClass

markAtomicEvent

public static void markAtomicEvent( EOEvent event, Object info)

Initializes event, a newly allocated event, as an atomic event, and assigns it's info to info. The newly allocated event is usually created with the EOEventCenter method newEventOfClass.

markEndOfEvent

public static void markEndOfEvent(EOEvent event)

Marks the time event ended.

markStartOfEvent

public static void markStartOfEvent( EOEvent event, Object info)

Marks event, a newly allocated event, to be a branch event (that possibly has nested subevents), and assigns it's info to info. The newly allocated event is usually created with newEventOfClass.

There is a limit on the number of events the event logging system logs-200,000 by default. You can change the limit using the user default EOEventLoggingLimit. When the logging limit is reached, the logging system attempts to purge old events before logging new ones. If the system is unable to purge old events, event logging is aborted.

The system's attempt to purge events can fail if the event logging limit is too small. This happens because the event system can't purge the first event logged, and it can't purge unclosed branch events.

newEventOfClass

public static EOEvent newEventOfClass( Class aClass, String aType)

Creates an event of the desired class and type.

password

public static String password()

Description forthcoming.

recordsEventsForClass

public static boolean recordsEventsForClass(Class eventClass)

Returns true if the application logs events of the eventClass class.

registerEventClass

public static void registerEventClass( Class aClass, EOEventCenter.EventRecordingHandler handler)

Registers aClass as an event class. The handler argument is an object that the event logging system notifies when event logging is enabled or disabled for aClass.

If the EOEventLoggingEnabled user default is set to true, this method enables logging for aClass. Programmatically, you can selectively enable or disable logging for a specific class with setRecordsEvents. It is more common, however, for users to enable and disable logging of a particular class through the WOEventSetup page-for more information, see "WOEventSetup page" (page 89).

When the event logging system enables logging for the ODBCAdaptorEvent class, it sends handler a setLoggingEnabled message with true as the flag and ODBCAdaptorEvent as the event class. handler is responsible for enabling logging in the instrumented code.

registeredEventClasses

public static NSArray registeredEventClasses()

Returns all the event classes registered in the application.

resetLoggingForAllCenters

public static void resetLoggingForAllCenters()

Discards all events in all event centers, restarting event collection for the entire application.

See Also: resetLogging

resumeLogging

public static void resumeLogging()

Resumes event logging in all centers. However, logging doesn't actually resume until each invocation of suspendLogging is paired with an invocation of resumeLogging. Invoking resumeLogging without a corresponding suspendLogging isn't harmful.

rootEventsByDuration

public static NSArray rootEventsByDuration()

Returns all root events from all event centers, sorted by decreasing duration.

See Also: rootEventsForAllCenters, rootEvents

rootEventsForAllCenters

public static NSArray rootEventsForAllCenters()

Returns all events from all event centers that are recorded at the root level; that is, it returns the events that don't have parent events.

See Also: rootEvents

setPassword

public static void setPassword(String aString)

Description forthcoming.

setRecordsEvents

public static void setRecordsEvents( boolean flag, Class eventClass)

Sets according to flag whether event centers record events of the eventClass class (and its subclasses). By default, event centers don't record events of any class. You can selectively enable logging for a particular event class with this method. To enable event logging for all event classes, set the user default EOEventLoggingEnabled. Then, you can selectively disable logging for a particular event with this method.

suspendLogging

public static void suspendLogging()

Suspends event logging in all event centers. Each invocation of suspendLogging must be paired with an invocation of resumeLogging to resume event logging.

Instance Methods

allEvents

public NSArray allEvents()

Returns the receiver's events (in no particular order).

eventsOfClass

public NSArray eventsOfClass( Class aClass, String type)

Returns the subset of the receiver's events that are instances of aClass and that have the type type. Specifying null for the class returns events of any class. Similarly, specifying null for the type returns events of any type.

resetLogging

public void resetLogging()

Discards all events in the event center for the calling thread.

See Also: resetLoggingForAllCenters

rootEvents

public NSArray rootEvents()

Returns the receiver's events that were recorded at root level; that is, returns the events that don't have a parent event.