EOEvent

Inherits from:
Object

Package:
com.webobjects.eocontrol

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

EOAttribute defines the following int constant as a possible signature type for use with the methods signatureOfType, aggregateEvents, and groupEvents.

EOBasicEventSignature

Additionally, EOEvent defines the following String 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.

EOEventGroupName

Method Types

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

Constructors

EOEvent

public EOEvent()

Description forthcoming.

Static Methods

aggregateEvents

public static NSArray aggregateEvents( NSArray events, int 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" (page 90).

classDescription

public static String classDescription(Class aClass)

Description forthcoming.

eventTypeDescriptions

public static NSDictionary eventTypeDescriptions(Class aClass)

Returns a dictionary of event types and descriptions for the family of events represented by the event class specified by aClass. The keys of this dictionary are event types and the corresponding values are descriptions of events of the types. Subclasses don't need to implement 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

public static NSArray groupEvents( NSArray events, int 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" (page 90).

Instance Methods

comment

public String comment()

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

description

public String 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.

displayComponentName

public String 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

public long 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

public long durationWithoutSubevents()

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

info

public Object info()

Returns the custom info for the receiver.

markAtomicWithInfo

public void markAtomicWithInfo(Object 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.

Note: Don't invoke this method directly. Use the corresponding method defined in EOEventCenter instead.

markEnd

public 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 method defined in EOEventCenter instead.

markStartWithInfo

public void markStartWithInfo(Object 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.

Note: Don't invoke this method directly. Use the corresponding method defined in EOEventCenter instead.

parentEvent

public EOEvent parentEvent()

Returns the parent event, if any, or null 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

public void setInfo(Object 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 equals and toString.

setType

public void setType(String 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

public String signatureOfType(int 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 signature type is unknown, EOEvent's implementation returns null otherwise.

See Also: aggregateEvents, groupEvents

startDate

public NSTimestamp 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

public NSArray subevents()

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

title

public String 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.

toString

public String toString()

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

type

public String 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.