com.webobjects.eocontrol
Class EOEvent

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

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

EOAggregateEvent, EODatabaseContext.DatabaseContextEvent, EOEditingContext.EditingContextEvent, WOEvent, WOStopWatch

public class EOEvent

extends Object

implements Serializable

EOEvent is an abstract class that provides concrete subclasses with a structure for storing information 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 default implementations are sufficient for most cases. Generally, to create a subclass of EOEvent, you declare it and create a description file that defines the events the 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.

Most of the work involved in logging custom events is instrumenting the code.

See Also:

eventTypeDescriptions(Class aClass), EOEventCenter, Serialized Form

Field Summary

static int	BasicEventSignature A possible signature type for use with the methods signatureOfType, aggregateEvents and groupEvents.
static String	EventGroupName Key used in the dictionary returned by eventTypeDescriptions.

Constructor Summary

EOEvent()
Creates a new event object.

Method Summary

static NSArray	aggregateEvents(NSArray events, int tag) Returns an array of aggregated events.
static String	classDescription(Class aClass) Returns a description of the family of events represented by the class aClass.
String	comment() Returns type-specific information about the event.
int	compare(EOEvent other) Compares the receiver to other.
String	description() Returns a String that includes the receiver's title, comment, and duration or start date (whichever is appropriate).
String	displayComponentName() Returns the name of a WebObjects component to use to display the receiver's logging information.
long	duration() Returns the duration of the receiver in milliseconds or 0 if the event is atomic (not a branch event) or if the branch is not yet closed.
long	durationWithoutSubevents() Returns the duration of the receiver in milliseconds, not including the time spent in its subevents (if any).
static NSDictionary	eventTypeDescriptions(Class aClass) Used to determine event types and descriptions for a family of events.
static NSArray	groupEvents(NSArray events, int tag) Returns an array of grouped events.
Object	info() Returns the custom info for the receiver.
void	markAtomicWithInfo(Object info) Initializes the receiver, a newly created event, as an atomic event that has an absolute start date (and not a duration), and sets its info to info.
void	markEnd() Marks the end of a branch event, which has the side effect of setting the duration.
void	markStartWithInfo(Object info) Initializes the receiver, a newly created event, to be a branch event (that possibly has nested subevents), and sets its info to info.
EOEvent	parentEvent() Returns the parent event, if any, or null otherwise.
void	setInfo(Object info) Sets the custom event information for the receiver.
void	setType(String type) Sets the receiver's type.
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.
NSTimestamp	startDate() Returns the date at which the receiver was logged.
NSArray	subevents() Returns the receiver's immediate subevents (events that were logged with this event as their parent).
String	title() Returns the event type description corresponding with the receiver's type.
String	toString() Returns a String that includes the receiver's title, comment, and duration or start date (whichever is appropriate).
String	type() Returns the receiver's type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BasicEventSignature

public static final int BasicEventSignature

A possible signature type for use with the methods signatureOfType, aggregateEvents and groupEvents.

See Also:

signatureOfType(int), aggregateEvents(NSArray, int), groupEvents(NSArray, int)

EventGroupName

public static final String EventGroupName

Key used in the dictionary returned by eventTypeDescriptions. The EventGroupName entry provides the description of the family of events represented by the event class.

See Also:

eventTypeDescriptions(Class)

Constructor Detail

EOEvent

public EOEvent()

Creates a new event object.

Method Detail

aggregateEvents

public static NSArray aggregateEvents(NSArray events,
                                      int tag)

Returns an array of aggregated events. Gets the signature of type tag from each EOEvent in events and aggregates the 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.

Parameters:

events - the array of EOEvents to group

tag - the tag indicating the type of the event

Returns:

an array of aggregated events

classDescription

public static String classDescription(Class aClass)

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

Parameters:

aClass - the event class to be described

Returns:

a description of the family of events represented by the class

See Also:

EventGroupName, eventTypeDescriptions(Class)

comment

public String comment()

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

Returns:

the type-specific information about the event

See Also:

info()

compare

public int compare(EOEvent other)

Compares the receiver to other. If the receiver was logged before the other event, this method returns NSComparator.OrderedAscending. If the receiver was logged after the other event, this method returns NSComparator.OrderedDescending. If the dates match, this method returns NSComparator.OrderedSame.

Parameters:

other - the EOEvent to be compared

Returns:

return the comparison result, one of NSComparator.OrderedAscending, NSComparator.OrderedDescending, or NSComparator.OrderedSame

description

public String description()

Returns a String that includes the receiver's title, comment, and duration or start date (whichever is appropriate).

Returns:

a description of the receiver

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.

Returns:

name of a WebObjects component to use to display the receiver's logging information

duration

public long duration()

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

Returns:

the duration of the receiver

durationWithoutSubevents

public long durationWithoutSubevents()

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

Returns:

the duration of the receiver, not including the time spent in its subevents

eventTypeDescriptions

public static NSDictionary eventTypeDescriptions(Class aClass)

Used to determine event types and descriptions for a family of events. 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 since 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 the event class represents, create a description file for the event and add it to the project's resources. 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 a CustomAdaptorEvent that would log events for a custom database adaptor. CustomAdaptorEvent would be a subclass of EOEvent and use EOEvent's implementation of eventTypeDescriptions. The name of its description file would be CustomAdaptorEvent.description, and it would look like this:

  { 
      EOEventGroupName = "Custom 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 CustomAdaptorEvent class, the other keys (connect, openChannel, and so on) would be the types of the events CustomAdaptorEvent 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 CustomAdaptorEvent).

Parameters:

aClass - the input event class

Returns:

the dictionary of event types and descriptions for the family of events represented by the event class

See Also:

EventGroupName

groupEvents

public static NSArray groupEvents(NSArray events,
                                  int tag)

Returns an array of grouped events. Gets the signature of type tag from each EOEvent 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.

Parameters:

events - the array of EOEvents to group

tag - the tag indicating the type of the event

Returns:

an array of grouped events

info

public Object info()

Returns the custom info for the receiver.

Returns:

the custom info for the receiver

markAtomicWithInfo

public void markAtomicWithInfo(Object info)

Initializes the receiver, a newly created event, as an atomic event that has an absolute start date (and not a duration), and sets its info to info. The new event object is usually created with the EOEventCenter method newEventOfClass.

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

Parameters:

info - the event's info object

See Also:

info(), startDate(), duration(), markStartWithInfo(Object), EOEventCenter.newEventOfClass(Class, String), EOEventCenter.markAtomicEvent(EOEvent, Object)

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.

See Also:

duration(), markStartWithInfo(Object), EOEventCenter.markEndOfEvent(EOEvent)

markStartWithInfo

public void markStartWithInfo(Object info)

Initializes the receiver, a newly created event, to be a branch event (that possibly has nested subevents), and sets its info to info. The new event object is usually created with the EOEventCenter method newEventOfClass.

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

Parameters:

info - the event's info object

See Also:

info(), markAtomicWithInfo(Object), EOEventCenter.newEventOfClass(Class, String), EOEventCenter.markStartOfEvent(EOEvent, Object)

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.

Returns:

the parent event, or null if there isn't one

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 implements the equals and toString methods.

Parameters:

info - the info object

setType

public void setType(String type)

Sets the receiver's type. EOEvent's default implementation gets the set of available types from a description file.

Parameters:

type - the string describing the type of the receiver

See Also:

eventTypeDescriptions(Class)

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, EOEvent.BasicEventSignature, which has the corresponding signature of the form "title-comment". If the specified signature type is unknown, EOEvent's implementation returns null.

Parameters:

tag - the tag indicating the type of the signature

Returns:

the receiver's signature

See Also:

BasicEventSignature, aggregateEvents(NSArray, int), groupEvents(NSArray, int)

startDate

public NSTimestamp startDate()

Returns the date at which the receiver was logged.

Returns:

the date at which the receiver was logged

subevents

public NSArray subevents()

Returns the receiver's immediate subevents (events that were logged with this event as their parent).

Returns:

the receiver's immediate subevents

title

public String title()

Returns the event type description corresponding with the receiver's type. The title is used by 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.

Returns:

the event type description corresponding with the receiver's type

See Also:

type(), eventTypeDescriptions(Class)

toString

public String toString()

Returns a String that includes the receiver's title, comment, and duration or start date (whichever is appropriate).

Overrides:

toString in class Object

Returns:

a description of the receiver

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.

Returns:

the receiver's event type

See Also:

eventTypeDescriptions(Class)