WebObjects 5.2

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)

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

Copyright © 2003 Apple Computer, Inc.