com.endeca.infront.perf

Class PerfUtil

java.lang.Object

com.endeca.infront.perf.PerfUtil

public class PerfUtil
extends Object

A static interface to ease the use of Assembler performance timing primitives. To time an event, write code similar to the following:

 Event event = PerfUtil.start("com.example.Foo#doStuff", "foo.doStuff(42)");
 try {
     foo.doStuff(42);
     event.succeed();
 } finally {
     event.failIfNotCompleted();
 }
 

Note the use of the Event.failIfNotCompleted() method. If the call to doStuff() completes successfully, then Event.succeed() will be invoked, completing the event. This means that when failIfNotCompleted() is called it will do nothing. If doStuff() throws an exception, however, succeed() will not be called, and failIfNotCompleted() will mark the event as having failed when it is invoked in the finally block.

Also notice the two arguments passed to start(String, String). The first argument is the event topic, which is used to determine which handlers the event will be sent to, while the second is an optional and arbitrary description of this particular instance of the event. Since some handlers may keep statistics aggregated by event topic, the topic should always be something static such as a class and method name. The topic should never contain information that is likely to be highly variable such as method arguments or request parameters; that sort of information should be placed in the description instead, as is shown in our example.

While all methods of this class are thread-safe, handlers passed to addHandler(String, EventHandler) must themselves be thread-safe. The event objects created by this class are NOT thread safe. Additionally, some handlers depend on all methods for a particular event being invoked from the same thread.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DESCRIPTION Key used to store the event description in the event property map

Method Summary

Methods

Modifier and Type	Method and Description
static void	addHandler(String topicPattern, EventHandler handler) Registers the given handler to receive Events with topics that match the specified pattern.
static void	removeHandler(EventHandler handler) Un-registers the given handler from all topic patterns.
static void	removeHandler(String topicPattern, EventHandler handler) Un-registers the given handler from the given topic pattern.
static <T> Event	start(Class<T> clazz, String name) Calls start(Class, String, String) with an empty description.
static <T> Event	start(Class<T> clazz, String name, String description) Computes an event name by combining the name of the given class with the given name (separated by an underscore), and then calls start(String, String).
static Event	start(String name) Calls start(String, String) with an empty description.
static Event	start(String topic, String description) Called to start and return a new event.

Methods inherited from class java.lang.Object

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

Field Detail

DESCRIPTION

public static final String DESCRIPTION

Key used to store the event description in the event property map

See Also:

Constant Field Values

Method Detail

addHandler

public static void addHandler(String topicPattern,
              EventHandler handler)

Registers the given handler to receive Events with topics that match the specified pattern. The pattern may include asterisks as wildcard characters which match zero or more arbitrary characters.

Please note: Handlers passed to this method may be invoked from multiple threads concurrently and MUST be thread-safe.

removeHandler

public static void removeHandler(EventHandler handler)

Un-registers the given handler from all topic patterns.

removeHandler

public static void removeHandler(String topicPattern,
                 EventHandler handler)

Un-registers the given handler from the given topic pattern.

start

public static <T> Event start(Class<T> clazz,
              String name)

Calls start(Class, String, String) with an empty description.

start

public static <T> Event start(Class<T> clazz,
              String name,
              String description)

Computes an event name by combining the name of the given class with the given name (separated by an underscore), and then calls start(String, String).

start

public static Event start(String name)

Calls start(String, String) with an empty description.

start

public static Event start(String topic,
          String description)

Called to start and return a new event.

Please Note: A call to start MUST always include a corresponding call to either the Event.succeed() or Event.fail() method of the returned Event, or undefined behavior will result. It is recommended to make use of the Event.failIfNotCompleted() helper method within a finally block in order to avoid making this mistake.

Additionally, Event objects may not be thread-safe, and some handlers may rely on all of the methods for a particular event being called from within the same thread.

Parameters:

topic - the event topic

description - an optional description of the event