com.sun.faban.driver
Class DriverContext

java.lang.Object
  com.sun.faban.driver.DriverContext

Direct Known Subclasses:

DriverContext, NullContext

public abstract class DriverContext
extends Object

DriverContext is the point of communication between the developer-provided driver and the Faban driver framework. Each thread has it's own context.

The only concrete implementation of this abstract class is in com.sun.faban.driver.engine.DriverContext.

Author:

Akara Sucharitakul

Constructor Summary

DriverContext()

Method Summary

abstract void	attachMetrics(CustomMetrics metrics) Attaches a custom metrics object to the primary metrics.
abstract void	attachMetrics(String name, CustomMetrics metrics) Attaches a custom metrics object to the primary metrics, given a name or description.
abstract void	attachMetrics(String name, CustomTableMetrics metrics) Attaches a custom table metrics object to the primary metrics, given a name or description.
abstract int	getAgentId() Obtains the agent id for this agent.
abstract String	getBaseDir() Obtains the base directory where the benchmark currently being run is installed.
abstract int	getClientsInAgent() Obtains the number of client threads in this agent.
abstract int	getClientsInDriver() Obtains the total number of clients threads for this driver.
static DriverContext	getContext() Obtains the DriverContext associated with this thread.
abstract String	getCurrentOperation() Obtains the name of the operation currently executing.
abstract String	getDriverName() Obtains the driver's name as annotated in the driver class.
abstract Logger	getLogger() Obtains the logger to be used by the calling driver.
abstract long	getNanoTime() Obtains a relative time, in nanosecs.
abstract int	getOperationCount() Obtains the number of operations active in this driver.
abstract int	getOperationId() Obtains the unique id assigned to the current operation type.
abstract Element	getPropertiesNode() Obtains the reference to the whole properties element as configured in the driverConfig element of this driver in the config file.
abstract String	getProperty(String name) Obtains a single-value property from the configuration.
abstract String[]	getPropertyValues(String name) Obtains a multiple-value property from the configuration.
abstract int	getRampDown() Obtains the configured ramp down time.
abstract int	getRampUp() Obtains the configured ramp up time.
abstract Random	getRandom() Obtains the per-thread random value generator.
abstract String	getResourceDir() Obtains the resource directory used for this benchmark, if exists.
abstract int	getScale() Obtains the scale or scaling rate of the current run.
abstract int	getSteadyState() Obtains the configured steady state time.
abstract int	getSteadyStateStart() Obtains the relative time - in milliseconds - that steady state starts, if set.
abstract long	getSteadyStateStartNanos() Obtains the relative time - in nanosecs - that steady state starts, if set.
abstract int	getThreadId() Obtains the global agent thread id for this context's thread.
abstract int	getTime() Obtains a relative time, in milliseconds.
abstract String	getXPathValue(String xPath) Reads the element or attribute by it's XPath.
abstract boolean	isTxSteadyState() Checks whether the driver is currently in steady state or not.
abstract void	pauseTime() Pauses the critical section so that operations made during the pause do not count into the response time.
abstract void	recordTime() Records the start time and end of the critical section of an operation.
abstract void	resetMix() Resets the state of the current mix to start off at the beginning of the mix.

Methods inherited from class java.lang.Object

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

Constructor Detail

DriverContext

public DriverContext()

Method Detail

getContext

public static DriverContext getContext()

Obtains the DriverContext associated with this thread.

Returns:

the associated DriverContext

getScale

public abstract int getScale()

Obtains the scale or scaling rate of the current run.

Returns:

the current run's scaling rate

getClientsInAgent

public abstract int getClientsInAgent()

Obtains the number of client threads in this agent.

Returns:

the number of client threads for this agent

getClientsInDriver

public abstract int getClientsInDriver()

Obtains the total number of clients threads for this driver.

Returns:

the number of client threads for this driver

getThreadId

public abstract int getThreadId()

Obtains the global agent thread id for this context's thread.

Returns:

the global agent thread id

getAgentId

public abstract int getAgentId()

Obtains the agent id for this agent.

Returns:

the current agent's id

getDriverName

public abstract String getDriverName()

Obtains the driver's name as annotated in the driver class.

Returns:

the driver name

getLogger

public abstract Logger getLogger()

Obtains the logger to be used by the calling driver.

Returns:

the appropriate logger

attachMetrics

public abstract void attachMetrics(CustomMetrics metrics)

Attaches a custom metrics object to the primary metrics. This should be done by the driver at initialization time. Only one custom metrics can be attached. Subsequent calls to this method replaces the previously attached metrics.

Parameters:

metrics - The custom metrics to be replaced

attachMetrics

public abstract void attachMetrics(String name,
                                   CustomMetrics metrics)

Attaches a custom metrics object to the primary metrics, given a name or description. The name/description must be unique. This should be done by the driver at initialization time. Only one custom metrics can be attached. Subsequent calls to this method replaces the previously attached metrics.

Parameters:

name - The name or description of this metrics

metrics - The custom metrics to be replaced

attachMetrics

public abstract void attachMetrics(String name,
                                   CustomTableMetrics metrics)

Attaches a custom table metrics object to the primary metrics, given a name or description. The name/description must be unique. This should be done by the driver at initialization time. Only one custom metrics can be attached. Subsequent calls to this method replaces the previously attached metrics.

Parameters:

name - The name or description of this metrics

metrics - The custom table metrics to be replaced

getCurrentOperation

public abstract String getCurrentOperation()

Obtains the name of the operation currently executing.

Returns:

the current operation's name

getOperationId

public abstract int getOperationId()

Obtains the unique id assigned to the current operation type. This id is commonly used to index into array structures containing operation-specific information such as stats. The id ranges from 0 to n where n is the number of operations in the driver less one.

Returns:

The unique id assigned to this operation type.

getOperationCount

public abstract int getOperationCount()

Obtains the number of operations active in this driver.

Returns:

The number of active operations

getRandom

public abstract Random getRandom()

Obtains the per-thread random value generator. Drivers should use this random value generator and not instantiate their own.

Returns:

The random value generator

isTxSteadyState

public abstract boolean isTxSteadyState()

Checks whether the driver is currently in steady state or not. This method needs to be called after the critical section of the operation. The transaction times must have been recorded in order to establish whether or not the transaction is in steady state.

Returns:

True if in steady state, false if not.

resetMix

public abstract void resetMix()

Resets the state of the current mix to start off at the beginning of the mix. For stateless mixes such as FlatMix, this operation does nothing.

recordTime

public abstract void recordTime()

Records the start time and end of the critical section of an operation. This operation may block until the appropriate start time for the operation has arrived. There is no blocking for the end time.

Throws:

IllegalStateException - if the operation uses auto timing

pauseTime

public abstract void pauseTime()

Pauses the critical section so that operations made during the pause do not count into the response time. If Timing.AUTO is used, the pause ends automatically when the next request is sent to the server. For manual timing, the next call to recordTime ends the pause.

getTime

public abstract int getTime()

Obtains a relative time, in milliseconds. This time is relative to a certain time at the beginning of the benchmark run and does not represent a wall clock time. All agents will have the same reference time. Use this time to check time durations during the benchmark run.

Returns:

The relative time of the benchmark run

getSteadyStateStart

public abstract int getSteadyStateStart()

Obtains the relative time - in milliseconds - that steady state starts, if set. The if the time is not yet set, it will return 0.

Returns:

The relative time steady state starts

getNanoTime

public abstract long getNanoTime()

Obtains a relative time, in nanosecs. This time is relative to a certain time at the beginning of the benchmark run and does not represent a wall clock time. All agents will have the same reference time. Use this time to check time durations during the benchmark run.

Returns:

The relative time of the benchmark run

getSteadyStateStartNanos

public abstract long getSteadyStateStartNanos()

Obtains the relative time - in nanosecs - that steady state starts, if set. The if the time is not yet set, it will return 0.

Returns:

The relative time steady state starts

getRampUp

public abstract int getRampUp()

Obtains the configured ramp up time.

Returns:

The configured ramp up time, in seconds

getSteadyState

public abstract int getSteadyState()

Obtains the configured steady state time.

Returns:

The configured steady state time, in seconds

getRampDown

public abstract int getRampDown()

Obtains the configured ramp down time.

Returns:

The configured ramp down time, in seconds

getProperty

public abstract String getProperty(String name)

Obtains a single-value property from the configuration. If the name of a multi-value property is given, only one value is returned. It is undefined as to which value in the list is returned.

Parameters:

name - The property name

Returns:

The property value

getPropertyValues

public abstract String[] getPropertyValues(String name)

Obtains a multiple-value property from the configuration. A single-value property will be returned as an array of dimension 1.

Parameters:

name - The property name

Returns:

The property values

getPropertiesNode

public abstract Element getPropertiesNode()

Obtains the reference to the whole properties element as configured in the driverConfig element of this driver in the config file. This method allows custom free-form structures but the driver will need to spend the effort walking the DOM tree.

Returns:

The DOM tree representing the properties node

getXPathValue

public abstract String getXPathValue(String xPath)
                              throws XPathExpressionException

Reads the element or attribute by it's XPath. The XPath is evaluated from the root of the configuration file.

Parameters:

xPath - The XPath to evaluate.

Returns:

The element or attribute value defined by the XPath

Throws:

XPathExpressionException - If the given XPath has an error

getBaseDir

public abstract String getBaseDir()

Obtains the base directory where the benchmark currently being run is installed.

Returns:

The benchmark's base directory

getResourceDir

public abstract String getResourceDir()

Obtains the resource directory used for this benchmark, if exists.

Returns:

The resource directory for this benchmark