Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOControl Reference

Table of Contents

EOEvent


Inherits from:
NSObject
Declared in:
EOControl/EOEvent.h



Class Description

EOEvent is an abstract class that provides concrete subclasses with a structure for storing information (such as duration) about a logged event.

Subclasses of EOEvent don't need to override any inherited methods or implement any methods at all. You can customize the behavior if you want, but the EOEvent implementations are sufficient for most cases. Generally, to create a subclass of EOEvent, you merely declare it and create a description file that defines the events your subclass logs. The class itself usually declares no instance variables and implements no methods. The abstract implementation gets all the information it needs from the description file. For more information on the description file, see the eventTypeDescriptions method description.

Most of the work involved in logging custom events is instrumenting your code. For more information on that and on the event logging system itself, see the EOEventCenter class specification.




Constants

In EOEvent.h, EOControl defines the int type EOEventSignatureType which is the argument type for the methods signatureOfType:, aggregateEvents:bySignatureOfType:, and groupEvents:bySignatureOfType:. EOEvent.h also defines the following enumeration constant as a possible signature type to be used as the argument to these methods.

Additionally, EOEvent.h defines the following NSString constant to be used as a key into the dictionary returned by eventTypeDescriptions. The EOEventGroupName entry provides the description of the family of events represented by the event class.



Method Types

Defining an event type
+ eventTypeDescriptions
+ description
Accessing information about the event
- description
- title
- startDate
- duration
- durationWithoutSubevents
- setType:
- type
- setInfo:
- info
- comment
Grouping and Aggregating Events
+ aggregateEvents:bySignatureOfType:
+ groupEvents:bySignatureOfType:
- signatureOfType:
Displaying event information
- displayComponentName
Traversing the event hierarchy
- parentEvent
- subevents
Logging events
- markAtomicWithInfo:
- markEnd
- markStartWithInfo:


Class Methods


aggregateEvents:bySignatureOfType:

+ (NSArray *)aggregateEvents:(NSArray *)events bySignatureOfType:(EOEventSignatureType)tag

Returns an array of aggregated events. Gets the signature of type tag from each event in events and aggregates events with the same signature into a special, single event. The resulting array has an event for each different signature. The events in this array have a duration equal to the sum of the durations of its aggregated events. The subevents of these special events are the union of the subevents of its aggregated events.

This method is for use by the WOEventDisplay page. For more information, see "WOEventDisplay page" .


description

+ (NSString *)description

Returns a description of the family of events represented by the class. EOEvent's implementation returns the event description for the EOEventGroupName key. For more information, see the eventTypeDescriptions method description.

eventTypeDescriptions

+ (NSDictionary *)eventTypeDescriptions

Returns a dictionary of event types and descriptions for the family of events represented by the event class. The keys of this dictionary are event types and the corresponding values are descriptions of events of the types. Subclasses don't need to override this method; EOEvent's implementation is generally sufficient for subclasses.

EOEvent's implementation reads the event types and their descriptions from a file. To define the types your event class represents, create a description file for your event and add it to your project's Resources folder. An event's description file defines the event categories and subcategories used in the WOEventDisplay page. The file's contents is a dictionary in plist format.

For example, consider the ODBCAdaptorEvent that logs events for the ODBC adaptor. ODBCAdaptorEvent is a subclass of EOEvent. It uses EOEvent's implementation of eventTypeDescriptions. The name of its description file is ODBCAdaptorEvent.description, and it looks like this:

{
    EOEventGroupName = "ODBC Adaptor Event";
    connect = "Connect";
    openChannel = "Open Channel";
    evaluateExpression = "Evaluate Expression";
    fetchRow = "Fetch Row";
    commitTransaction = "Commit Transaction";
}

Using the EOEvent implementation, the EOEventGroupName entry is mandatory; it describes the family of events logged by the event class. Any other keys are defined by the event class itself. In the ODBCAdaptorEvent class, the other keys (connect, openChannel, and so on) are the types of the events ODBCAdaptorEvent logs.

If the file doesn't exist or if there's an error reading the file, EOEvent creates a dictionary with a single entry; the entry's key is EOEventGroupName and the value is the name of the event class (such as ODBCAdaptorEvent).


groupEvents:bySignatureOfType:

+ (NSArray *)groupEvents:(NSArray *)events bySignatureOfType:(EOEventSignatureType)tag

Returns an array of grouped events. Gets the signature of type tag from each event in events and groups events with the same signature into a special, single event. The resulting array has an event for each different signature. The subevents of these special events are the grouped events.

This method is for use by the WOEventDisplay page. For more information, see "WOEventDisplay page" .



Instance Methods


comment

- (NSString *)comment

Returns type specific information about the event. EOEvent's implementation returns a string representation of the receiver's info.

description

- (NSString *)description

Returns a description of the receiver. EOEvent's implementation returns a string that includes the receiver's title, comment, and duration or startDate.

displayComponentName

- (NSString *)displayComponentName

Returns the name of a WebObjects component to use to display the receiver's logging information. EOEvent's implementation uses the WOEventRow component, which is generally sufficient for subclasses.

duration

- (int)duration

Returns the duration of the receiver, in milliseconds; returns 0 if the event is atomic (not a branch event) or if the branch is not yet closed.

durationWithoutSubevents

- (int)durationWithoutSubevents

Returns the duration of receiver, in milliseconds, not including the time spent in its subevents (if any).

info

- (id)info

Returns the custom info for the receiver.

markAtomicWithInfo:

- (void)markAtomicWithInfo:(id)info

Initializes the receiver, a newly allocated event, as an atomic event that has an absolute startDate (and not a duration), and assigns the event's info. The newly allocated event is usually created with the EOEventCenter method newEventOfClass:eventType:.
Note: Don't invoke this method directly. Use the corresponding function defined in EOEventCenter.h instead.


markEnd

- (void)markEnd

Marks the end of a branch event, which has the side-effect of setting the duration.
Note: Don't invoke this method directly. Use the corresponding function defined in EOEventCenter.h instead.


markStartWithInfo:

- (void)markStartWithInfo:(id)info

Initializes the receiver, 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 the EOEventCenter method newEventOfClass:eventType:.
Note: Don't invoke this method directly. Use the corresponding function defined in EOEventCenter.h instead.


parentEvent

- (EOEvent *)parentEvent

Returns the parent event, if any, or nil otherwise. Events logged at the root level do not have a parent. Other events return the event that was open at the time that they were started.

setInfo:

- (void)setInfo:(id)info

Sets the custom event information for the receiver. This information is used to display event logging information in the WOEventDisplay page. The info argument can be any kind of object that responds to isEqual:, description, retain, and release.

setType:

- (void)setType:(NSString *)type

Sets the receiver's type to type. EOEvent's implementation gets the set of available types from a description file. For more information, see the eventTypeDescriptions method description.

signatureOfType:

- (id)signatureOfType:(EOEventSignatureType)tag

Returns the requested receiver's signature, which can be used to group and aggregate the receiver with other events that have the same signature. EOEvent defines one signature type, EOBasicEventSignature, which has the corresponding signature of the form "title - comment". If the specified type is unknown, EOEvent's implementation returns nil otherwise.

See Also: + aggregateEvents:bySignatureOfType:, + groupEvents:bySignatureOfType:


startDate

- (NSCalendarDate *)startDate

Returns the date at which the receiver was logged. For a non-atomic event, the return value is the time at which the event logging began, not when it ended.

subevents

- (NSArray *)subevents

Returns the receiver's immediate subevents; that is, the events that were logged with this event as their parent.

title

- (NSString *)title

Returns the event type description corresponding with the receiver's type. The title is used by the WOEventDisplay. EOEvent's implementation returns the value from the eventTypeDescriptions dictionary for the receiver's type. If there isn't an entry in the eventTypeDescriptions dictionary for the receiver's type, EOEvent's implementation returns the name of the receiver's class.

type

- (NSString *)type

Returns the receiver's type. Using the event type definition scheme implemented by EOEvent, the types are defined in a description file as described in the eventTypeDescriptions method description.


Table of Contents