WebObjects 5.2

com.webobjects.eocontrol
Class EOEventCenter

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOEventCenter

public class EOEventCenter
extends Object

EOEventCenter collects and manages EOEvents to measure the duration of operations in any 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.

The event logging system defined by EOEventCenter and EOEvent allow the measurement of the length of certain instrumented operations. An EOEvent keeps information (such as duration and type) about a logged event, and an EOEventCenter manages those events. EOEvent is an abstract class whose subclasses are responsible for defining the events they track. For example, there are (private) subclasses for adaptor events, editing context events, WOApplication events, and so on. To enable event logging in an application, simply open the WOEventSetup page as described in WOEventSetup and enable logging for the event classes.

In addition to the framework support, the WOExtensions framework provides components for using the feature. WOEventSetup is a page used to configure event logging, and WOEventDisplay is a page that displays event information.

See EOEventCenterConcepts for more information.

See Also:
EOEvent, WOEventSetup

Inner Class Summary
static interface EOEventCenter.EventRecordingHandler
          The EOEventCenter.EventRecordingHandler interface declares the setLoggingEnabled method, which is invoked by the event-logging system when logging is enabled or disabled for an event class.
 
Field Summary
static String EventLoggingEnabled
          Name of the system property (a Boolean value) defining whether or not to log registered event classes by default.
static String EventLoggingLimit
          Name of the system property (an Integer value) defining the maximum size of the event logging stack.
static String EventLoggingOverflowDisplay
          Name of the system property (a Boolean value) defining whether an event log overflow should be logged.
static String EventLoggingPassword
          Name of the system property (a String value) defining the password which allows access to event logging information.
 
Constructor Summary
EOEventCenter()
          Creates a new event center.
 
Method Summary
static NSArray allCenters()
          Returns all event centers.
 NSArray allEvents()
          Returns an array of the receiver's events (in no particular order).
static NSArray allEventsForAllCenters()
          Returns an array of all events logged in all the event centers (in no particular order).
static void cancelEvent(EOEvent anEvent)
          Cancels the recording of an in-progress event.
static EOEventCenter currentCenter()
          Returns the event center for the calling thread.
 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.
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.
static void markAtomicEvent(EOEvent anEvent, Object info)
          Marks anEvent, a newly created event, as an atomic event, and assigns it's info to info.
static void markEndOfEvent(EOEvent anEvent)
          Marks the time anEvent ended.
static void markStartOfEvent(EOEvent anEvent, Object info)
          Marks anEvent, a newly created event, to be a branch event (that possibly has nested subevents), and assigns it's info to info.
static EOEvent newEventOfClass(Class aClass, String type)
          Creates an event of the desired class and type.
static String password()
          Returns the password which allows access to event logging information.
static boolean recordsEventsForClass(Class eventClass)
          Returns true if the application logs events of the eventClass class, or false otherwise.
static NSArray registeredEventClasses()
          Returns an array of all event classes registered in the application.
static void registerEventClass(Class aClass, EOEventCenter.EventRecordingHandler handler)
          Registers aClass as an event class.
 void resetLogging()
          Discards all events in the event center for the calling thread.
static void resetLoggingForAllCenters()
          Discards all events in all event centers, restarting event collection for the entire application (that is, for all threads).
static void resumeLogging()
          Resumes event logging in all centers.
 NSArray rootEvents()
          Returns the receiver's events that were recorded at the root level; that is, returns the events that don't have a parent event.
static NSArray rootEventsByDuration()
          Returns the events from all event centers that are recorded at root level, sorted by decreasing duration.
static NSArray rootEventsForAllCenters()
          Returns the events from all event centers that are recorded at root level.
static void setPassword(String p)
          Sets the password which allows access to event logging information.
static void setRecordsEvents(boolean flag, Class eventClass)
          Sets according to flag whether event centers record events of the eventClass class (and its subclasses).
static void suspendLogging()
          Suspends event logging in all event centers.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EventLoggingEnabled

public static final String EventLoggingEnabled
Name of the system property (a Boolean value) defining whether or not to log registered event classes by default.

EventLoggingLimit

public static final String EventLoggingLimit
Name of the system property (an Integer value) defining the maximum size of the event logging stack.

EventLoggingOverflowDisplay

public static final String EventLoggingOverflowDisplay
Name of the system property (a Boolean value) defining whether an event log overflow should be logged.

EventLoggingPassword

public static final String EventLoggingPassword
Name of the system property (a String value) defining the password which allows access to event logging information.

The String value is "EOEventLoggingPassword".

Constructor Detail

EOEventCenter

public EOEventCenter()
Creates a new event center. Note that new instances of EOEventCenter should be retrieved through the static method currentCenter instead of via this constructor.
See Also:
currentCenter()
Method Detail

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.
Returns:
an array of all event centers
See Also:
currentCenter()

allEvents

public NSArray allEvents()
Returns an array of the receiver's events (in no particular order).
Returns:
an array of the receiver's events
See Also:
allEventsForAllCenters()

allEventsForAllCenters

public static NSArray allEventsForAllCenters()
Returns an array of all events logged in all the event centers (in no particular order).
Returns:
an array of all events logged in all the event centers

cancelEvent

public static void cancelEvent(EOEvent anEvent)

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 an event will be canceled when the operation being logged is aborted. For example, an adaptor channel cancels an "Open Channel" event if the openChannel method doesn't successfully open a connection to the database.

Parameters:
anEvent - the event to cancel
See Also:
markEndOfEvent(EOEvent)

currentCenter

public static EOEventCenter currentCenter()
Returns the event center for the calling thread. Note that this is the normal manner in which an EOEventCenter is retrieved: if one does not yet exist for the calling thread, it is created and initialized.
Returns:
the event center for the calling thread
See Also:
allCenters()

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.
Parameters:
aClass - the event class to look for
type - the type of the events to look for
Returns:
the subset of the receiver's events that are instances the specified class and have the specified type

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.
Parameters:
aClass - the event class to look for
type - the type of the events to look for
Returns:
an array of all events (from all event centers) that are instances of the specified class and have the specified type
See Also:
eventsOfClass(Class, String)

markAtomicEvent

public static void markAtomicEvent(EOEvent anEvent,
                                   Object info)
Marks anEvent, a newly created event, as an atomic event, and assigns it's info to info. The new event object is usually created with newEventOfClass.
Parameters:
anEvent - the event to mark
info - the event info
See Also:
newEventOfClass(Class, String)

markEndOfEvent

public static void markEndOfEvent(EOEvent anEvent)
Marks the time anEvent ended.
Parameters:
anEvent - the event whose ending is logged

markStartOfEvent

public static void markStartOfEvent(EOEvent anEvent,
                                    Object info)

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

There is a limit on the number of events the event logging system logs. This is 200,000 by default, but can be changed using the system property 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.

Parameters:
anEvent - the event to mark
info - the event info
See Also:
newEventOfClass(Class, String)

newEventOfClass

public static EOEvent newEventOfClass(Class aClass,
                                      String type)
Creates an event of the desired class and type.
Parameters:
aClass - the event class to instantiate
type - the type of the event for the class
Returns:
an event of the desired class and type.
See Also:
EOEvent.setType(String)

password

public static String password()
Returns the password which allows access to event logging information.
Returns:
the password

recordsEventsForClass

public static boolean recordsEventsForClass(Class eventClass)
Returns true if the application logs events of the eventClass class, or false otherwise.
Parameters:
eventClass - the event class to check
Returns:
true if the application logs events of the event class; false otherwise
See Also:
setRecordsEvents(boolean, Class), registerEventClass(Class, EOEventCenter.EventRecordingHandler)

registerEventClass

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

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

If the EOEventLoggingEnabled system property is set to true, this method enables logging for aClass. Programmatically, you can selectively enable or disable logging for a specific class with setRecordsEvents.

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

Parameters:
aClass - the class to be registered
handler - the object notified by event logging system when logging is enabled or disabled
See Also:
setRecordsEvents(boolean, Class), EOEventCenter.EventRecordingHandler

registeredEventClasses

public static NSArray registeredEventClasses()
Returns an array of all event classes registered in the application.
Returns:
an array of all event classes registered in the application

resetLogging

public void resetLogging()
Discards all events in the event center for the calling thread.
See Also:
resetLoggingForAllCenters()

resetLoggingForAllCenters

public static void resetLoggingForAllCenters()
Discards all events in all event centers, restarting event collection for the entire application (that is, for all threads).
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.
See Also:
suspendLogging()

rootEvents

public NSArray rootEvents()
Returns the receiver's events that were recorded at the root level; that is, returns the events that don't have a parent event.
Returns:
the receiver's events that were recorded at root level
See Also:
rootEventsForAllCenters(), rootEventsByDuration()

rootEventsByDuration

public static NSArray rootEventsByDuration()
Returns the events from all event centers that are recorded at root level, sorted by decreasing duration.
Returns:
the sorted events from all event centers that are recorded at the root level
See Also:
rootEventsForAllCenters(), rootEvents()

rootEventsForAllCenters

public static NSArray rootEventsForAllCenters()
Returns the events from all event centers that are recorded at root level.
Returns:
the events from all event centers that are recorded at the root level
See Also:
rootEvents(), rootEventsByDuration()

setPassword

public static void setPassword(String p)
Sets the password which allows access to event logging information.
Parameters:
p - the password

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 system property EOEventLoggingEnabled. Then, you can selectively disable logging for a particular event with this method.
Parameters:
flag - true if event centers should record events of the event class; false otherwise
eventClass - the class for which events should be recorded or not
See Also:
recordsEventsForClass(Class), registerEventClass(Class, EOEventCenter.EventRecordingHandler)

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.
See Also:
resumeLogging()

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.