oracle.dms.instrument
Class PhaseEvent

java.lang.Object
oracle.dms.instrument.Sensor
oracle.dms.instrument.PhaseEvent

public class PhaseEvent

extends Sensor

A PhaseEvent is used to measure important intervals, phases, or blocks of code. Programs call the start() method when the beginning of the interval and the stop() method at the end of the interval. DMS then exports measurements of the duration of the interval, the number of times the event occurred, the minimum and maximum phase duration, and the number of threads currently executing between the start() and stop() markers. Depending on the derived metrics specified, a PhaseEvent sensor may contain time, maximum, minimum, completed, average, active, and maxActive metrics.

Field Summary

Fields inherited from class oracle.dms.instrument.Sensor

active, all, average, completed, count, exclTime, maxActive, maximum, minimum, sum, time, value

Method Summary

void	abort(long token) Aborts the measurement of a phase.
static PhaseEvent	create(Noun parent, java.lang.String name, java.lang.String desc) Creates a new PhaseEvent.
void	deriveMetric(int metric) Instructs the PhaseEvent to derive additional metrics.
long	start() Signals the beginning of the phase.
void	start(long startToken) Signals the beginning of the phase.
void	stop(long token) Signals the end of the Phase.
void	stop(long startToken, long stopToken) Signals the end of the phase.
long	stop2(long token) Signals the end of the phase.

Methods inherited from class oracle.dms.instrument.Sensor

destroy, get, getDescription, getName, getValue, reset

Methods inherited from class java.lang.Object

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

Method Detail

create

public static PhaseEvent create(Noun parent,
                                java.lang.String name,
                                java.lang.String desc)

Creates a new PhaseEvent.

Parameters:

parent - the parent Noun

name - the name of the PhaseEvent

desc - the description of the PhaseEvent

Returns:

the new PhaseEvent or, if the PhaseEvent already exists, then this method returns a reference to it.

Since:

Oracle iAS 1.0.2.2

deriveMetric

public void deriveMetric(int metric)

Instructs the PhaseEvent to derive additional metrics. Once a metric has been derived, it cannot be turned off.

Overrides:

deriveMetric in class Sensor

Parameters:

metric - bitmask of metric(s) to be derived.

Possible values are Sensor.minimum, Sensor.maximum, Sensor.completed, Sensor.average, Sensor.active, Sensor.maxActive and Sensor.all (shorthand for all of the applicable derivations). The values can be bitwise-ORed together, or multiple calls to deriveMetric can be made.

Since:

Oracle iAS 1.0.2.2

start

public long start()

Signals the beginning of the phase.

Returns:

a token value (timestamp) that must be passed to stop(long token)

Since:

Oracle iAS 1.0.2.2

See Also:

stop(long token)

stop

public void stop(long token)

Signals the end of the Phase. It is recommended that this method should be put in a finally block, while start() is put in a try block.

   long token;
   PhaseEvent phase;

   try
   {
     token = phase.start();
     // ... do something ...
   }
   finally
   {
     phase.stop(token);
   }
 

Parameters:

token - the token obtained at the start of the phase

Since:

Oracle iAS 1.0.2.2

stop2

public long stop2(long token)

Signals the end of the phase.

Parameters:

token - the token obtained at the start of the phase

Returns:

a token value (timestamp) that can be passed to stop(long startToken, long stopToken)

Since:

Oracle Application Server 10g (9.0.4.1)

See Also:

start()

start

public void start(long startToken)

Signals the beginning of the phase. This method is used when several phases start at the same time and you want them all to share the same timestamp.

Parameters:

startToken - the token signifying the beginning of the phase. Usually this token is obtained from a call to start()

Since:

Oracle iAS 9.0.2

See Also:

start()

stop

public void stop(long startToken,
                 long stopToken)

Signals the end of the phase. This method is generally used when several phases end at the same time and you want all of them to share the same timestamp.

Parameters:

startToken - the token returned by the corresponding start() call

stopToken - the token signifying the end of the phase that is obtained from a call to stop2(long token)

Since:

Oracle iAS 9.0.2

See Also:

stop2(long token)

abort

public void abort(long token)

Aborts the measurement of a phase. The following is an example showing how one might use this method.

   long token;
   PhaseEvent phase;
   boolean stopped = false;

   try
   {
     token = phase.start();
     // ... do something ...
     phase.stop(token);    // placed at bottom of try block
     stopped = true;       // placed at bottom of try block
   }
   finally
   {
     if (!stopped)
       phase.abort(token);
   }
 

Parameters:

token - the token obtained at the start of the phase

Since:

Oracle iAS 9.0.2