oracle.adf.share.perf
Class Timer

java.lang.Object
  oracle.adf.share.logging.internal.perf.ADFPerfSensor
      oracle.adf.share.perf.Timer

public class Timer
extends ADFPerfSensor

This class is a wrapper of DMS PhaseEvent sensor. It encapsulates sensor group name(Noun) and sensor name. It also contains a pair of functions to start()/stop() the timer, and a cleanup() function to abort the timer in the case of an exception so that we only count those PhaseEvents that are successfully stopped.

Field Summary

static Timer

DUMMY_TIMER An empty Timer object.

Fields inherited from class oracle.adf.share.logging.internal.perf.ADFPerfSensor

mEnableDms, mEnablePerfLog, mIndex, mLevel, mSensorFullName, sIdxLogger, sLogger

Constructor Summary

protected

Timer() creates an empty Timer object.

Method Summary

void	cleanup() Cleanup the timer.
void	cleanupWithToken(TimerToken token) Cleanup the timer using token.
static Timer	createTimer(java.util.logging.Level level, java.lang.String groupName, java.lang.String name, java.lang.String desc) Create a Timer object identified by the groupName, the name, and the description.
static Timer	createTimer(java.util.logging.Level level, java.lang.String groupName, java.lang.String name, java.lang.String type, java.lang.String desc) Create a Timer object identified by the groupName, the name, the type, and the description.
static Timer	createTimer(java.util.logging.Level level, java.lang.String groupName, java.lang.String name, java.lang.String type, java.lang.String desc, TimerProvider provider) Create a summerized Timer object identified by the groupName, the name, the type, the description, and a bunch of sub timers provided by the provider.
static Timer	createTimer(java.util.logging.Level level, java.lang.String groupName, java.lang.String name, java.lang.String desc, TimerProvider provider) Create a composite timer object identified by the groupName, the name, the description, and a timer provider.
void	reset() Clean up the metrics value
void	start() Start the timer.
TimerToken	startWithToken() Start the timer using Token.
void	stop() Stop the timer.
void	stop(int returnValue) Stop the timer with specified returnValue
void	stop(java.lang.Object returnValue) Stop the timer with specified returnValue
void	stopWithToken(TimerToken token) Stop the timer using token.
void	stopWithToken(TimerToken token, int returnValue) Stop the timer using token with specified returnValue
void	stopWithToken(TimerToken token, java.lang.Object returnValue) Stop the timer using token with specified returnValue

Methods inherited from class oracle.adf.share.logging.internal.perf.ADFPerfSensor

isActive, log

Methods inherited from class java.lang.Object

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

Field Detail

DUMMY_TIMER

public static final Timer DUMMY_TIMER

An empty Timer object. Does nothing. Allows client code to be written in a generic way without knowing whether the code is executing in the IDE or in a deployed application.

Constructor Detail

Timer

protected Timer()

creates an empty Timer object.

Method Detail

createTimer

public static Timer createTimer(java.util.logging.Level level,
                                java.lang.String groupName,
                                java.lang.String name,
                                java.lang.String desc)

Create a Timer object identified by the groupName, the name, and the description.

Developers should then call Timer's start(), stop() and cleanup() functions to track the time. Please note start()/stop() funtions should always be put in a try or catch block, and the cleanup() function should always be called in a finally block to make sure the Timer object is aborted cleanly in case stop() is not called.

Internally, this method creates a DMS PhaseEvent sensor.

A DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

When called inside the IDE, always returns DUMMY_TIMER.

Parameters:

level - one of the message level identifiers, e.g. SEVERE

groupName - the group name, which has the format of /oracle/component_id/module/subModule/... The component_id is also used as timer type

name - the timer name

desc - the description for this timer.

Returns:

Timer the new Timer

createTimer

public static Timer createTimer(java.util.logging.Level level,
                                java.lang.String groupName,
                                java.lang.String name,
                                java.lang.String desc,
                                TimerProvider provider)

Create a composite timer object identified by the groupName, the name, the description, and a timer provider.

Developers should then call Timer's start(), stop(returnValue) and cleanup() functions to track the time. Please note start()/stop(returnValue) funtions should always be put in a try or catch block, and the cleanup() function should always be called in a finally block to make sure the Timer object is aborted cleanly in case stop(returnValue) is not called.

Internally, this method creates one or more DMS PhaseEvent sensors depending on the implementation of TimerProvider.

A DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

When called inside the IDE, always returns DUMMY_TIMER.

Parameters:

level - one of the message level identifiers, e.g. SEVERE

groupName - the group name, which has the format of /oracle/component_id/module/subModule/... The component_id is also used as timer type

name - the timer name

desc - the description for this timer.

provider - the timer provider implements TimerProvider

Returns:

Timer the new composite Timer

createTimer

public static Timer createTimer(java.util.logging.Level level,
                                java.lang.String groupName,
                                java.lang.String name,
                                java.lang.String type,
                                java.lang.String desc)

Create a Timer object identified by the groupName, the name, the type, and the description.

Developers should then call Timer's start(), stop() and cleanup() functions to track the time. Please note start()/stop() funtions should always be put in a try or catch block, and the cleanup() function should always be called in a finally block to make sure the Timer object is aborted cleanly in case stop() is not called.

Internally, this method creates a DMS PhaseEvent sensor.

A DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

When called inside the IDE, always returns DUMMY_TIMER.

Parameters:

level - one of the message level identifiers, e.g. SEVERE

groupName - the group name, which has the format of /oracle/component_id/module/subModule/...

name - the timer name

type - the timer type which collects all sensors with same type and display them together in a table in AggreSpy

desc - the description for this timer.

Returns:

Timer the new Timer

createTimer

public static Timer createTimer(java.util.logging.Level level,
                                java.lang.String groupName,
                                java.lang.String name,
                                java.lang.String type,
                                java.lang.String desc,
                                TimerProvider provider)

Create a summerized Timer object identified by the groupName, the name, the type, the description, and a bunch of sub timers provided by the provider.

Developers should then call Timer's start(), stop(returnValue) and cleanup() functions to track the time. Please note start()/stop(returnValue) funtions should always be put in a try or catch block, and the cleanup() function should always be called in a finally block to make sure the Timer object is aborted cleanly in case stop(returnValue) is not called.

Internally, this method creates one or more DMS PhaseEvent sensors depending on the implementation of TimerProvider.

A DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

When called inside the IDE, always returns DUMMY_TIMER.

Parameters:

level - one of the message level identifiers, e.g. SEVERE

groupName - the group name, which has the format of /oracle/component_id/module/subModule/...

name - the timer name

type - the timer type which collects all sensors with same type and display them together in a table in AggreSpy

desc - the description for this timer.

provider - the timer provider implements TimerProvider

Returns:

Timer the new Timer

start

public void start()

Start the timer.

After a timer is started, developers should call stop() function to stop the timer. start()/stop() funtions should be put in a try block, and the cleanup() function should be called in a finally block.

Internally, this method starts the DMS PhaseEvent sensor. The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

startWithToken

public TimerToken startWithToken()

Start the timer using Token. Normally this method is only used when the timer starts and stops in different thread. Otherwise, the simpler version of start()/stop() should be used.

After a timer is started, developer should call stopWithToken(token) and cleanupWithToekn(token) function to stop and cleanup the timer.

Internally, this method starts the DMS PhaseEvent sensor. The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Returns:

token of the timer

stop

public void stop()

Stop the timer.

Developer should call start() function to start the timer. start()/stop() functions should be put in a try block, and the cleanup() function should be called in a finally block.

Internally, this method stops the DMS PhaseEvent sensor. The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

stopWithToken

public void stopWithToken(TimerToken token)

Stop the timer using token.

Developer should call startWithToken() function to start the timer, and then call this method to stop the timer

Internally, this method stops the DMS PhaseEvent sensor. The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Parameters:

token - the TimerToken returned from startWithToken()

stop

public void stop(int returnValue)

Stop the timer with specified returnValue

Developer should call start() function to start the timer with TimerProvider, and stop(returnValue) to stop the timer. The returnValue decides which children timers to be updated.

Internally, this method stops the DMS PhaseEvent sensor for the parent sensor, and then update each children's PhaseEvent based on the result from TimerProvider.getTimers().

The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Parameters:

returnValue - the return code from a piece of code being monitored.

stopWithToken

public void stopWithToken(TimerToken token,
                          int returnValue)

Stop the timer using token with specified returnValue

Developer should call startWithToken() function to start the timer with TimerProvider, and stopWithToken(token, returnValue) to stop the timer. The returnValue decides which children timers to be updated.

Internally, this method stops the DMS PhaseEvent sensor for the parent sensor, and then update each children's PhaseEvent based on the result from TimerProvider.getTimers().

The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Parameters:

token - the TimerToken returned from startWithToken()

returnValue - the return code from a piece of code being monitored.

stop

public void stop(java.lang.Object returnValue)

Stop the timer with specified returnValue

Developer should call start() function to start the timer with TimerProvider, and stop(returnValue) to stop the timer. The returnValue decides which children timers to be updated.

Internally, this method stops the DMS PhaseEvent sensor for the parent sensor, and then update each children's PhaseEvent based on the result from TimerProvider.getTimers().

The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Parameters:

returnValue - the return code from a piece of code being monitored.

stopWithToken

public void stopWithToken(TimerToken token,
                          java.lang.Object returnValue)

Stop the timer using token with specified returnValue

Developer should call startWithToken() function to start the timer with TimerProvider, and stopWithToken(token, returnValue) to stop the timer. The returnValue decides which children timers to be updated.

Internally, this method stops the DMS PhaseEvent sensor for the parent sensor, and then update each children's PhaseEvent based on the result from TimerProvider.getTimers().

The DMS PhaseEvent sensor has following metrics: active, avg, completed, maxActive, maxTime, minTime and time.

Parameters:

token - the TimerToken returned from startWithToken()

returnValue - the return code from a piece of code being monitored.

cleanup

public void cleanup()

Cleanup the timer.

This function should be called within a finally block. It either stops the timer if everything goes fine, or aborts the timer if an exception occurred.

cleanupWithToken

public void cleanupWithToken(TimerToken token)

Cleanup the timer using token.

This function should be called within a finally block. It either stops the timer if everything goes fine, or aborts the timer if an exception occurred.

Parameters:

token - the TimerToken returned from startWithToken()

reset

public void reset()

Description copied from class: ADFPerfSensor

Clean up the metrics value

Overrides:

reset in class ADFPerfSensor