com.sun.faban.driver.engine
Class DriverContext

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

public class DriverContext
extends DriverContext

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

This class provides the actual implementation and is located in the engine package to get direct access to all the restricted/needed classes and members.

Author:

Akara Sucharitakul

Nested Class Summary

static class

DriverContext.TimingInfo TimingInfo is a value object that contains individual timing records for each operation.

Method Summary

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

Methods inherited from class java.lang.Object

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

Method Detail

getContext

public static DriverContext getContext()

Obtains the DriverContext associated with this thread.

Returns:

the associated DriverContext

getScale

public int getScale()

Obtains the scale or scaling rate of the current run.

Specified by:

getScale in class DriverContext

Returns:

the current run's scaling rate

getClientsInAgent

public int getClientsInAgent()

Obtains the number of client threads in this agent.

Specified by:

getClientsInAgent in class DriverContext

Returns:

the number of client threads

getClientsInDriver

public int getClientsInDriver()

Obtains the total number of clients threads for this driver.

Specified by:

getClientsInDriver in class DriverContext

Returns:

the number of client threads for this driver

getThreadId

public int getThreadId()

Obtains the global thread id for this context's thread. The thread id is unique for each driver type.

Specified by:

getThreadId in class DriverContext

Returns:

the global agentImpl thread id

getAgentId

public int getAgentId()

Obtains the agent id for this agentImpl.

Specified by:

getAgentId in class DriverContext

Returns:

the current agentImpl's id

getDriverName

public String getDriverName()

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

Specified by:

getDriverName in class DriverContext

Returns:

the driver name

getLogger

public Logger getLogger()

Obtains the logger to be used by the calling driver.

Specified by:

getLogger in class DriverContext

Returns:

the appropriate logger

getCurrentOperation

public String getCurrentOperation()

Obtains the name of the operation currently executing.

Specified by:

getCurrentOperation in class DriverContext

Returns:

the current operation's name, or null if called from outside an operation.

getOperationId

public 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.

Specified by:

getOperationId in class DriverContext

Returns:

The unique id assigned to this operation type, or -1 if called from outside an operation.

getOperationCount

public int getOperationCount()

Obtains the number of operations active in this driver.

Specified by:

getOperationCount in class DriverContext

Returns:

The number of active operations

getRandom

public Random getRandom()

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

Specified by:

getRandom in class DriverContext

Returns:

The random value generator

resetMix

public 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.

Specified by:

resetMix in class DriverContext

attachMetrics

public 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.

Specified by:

attachMetrics in class DriverContext

Parameters:

metrics - The custom metrics to be replaced

attachMetrics

public 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.

Specified by:

attachMetrics in class DriverContext

Parameters:

name - The name or description of this metrics

metrics - The custom metrics to be replaced

attachMetrics

public 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.

Specified by:

attachMetrics in class DriverContext

Parameters:

name - The name or description of this metrics

metrics - The custom metrics to be replaced

getProperty

public 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.

Specified by:

getProperty in class DriverContext

Parameters:

name - The property name

Returns:

The property value, or null if there is no such property

getPropertyValues

public 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.

Specified by:

getPropertyValues in class DriverContext

Parameters:

name - The property name

Returns:

The property values

getPropertiesNode

public 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.

Specified by:

getPropertiesNode in class DriverContext

Returns:

The DOM tree representing the properties node

isTxSteadyState

public 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.

Specified by:

isTxSteadyState in class DriverContext

Returns:

True if in steady state, false if not.

getXPathValue

public 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.

Specified by:

getXPathValue in class DriverContext

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

recordTime

public void recordTime()

Records the start and end time 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. This method is for use in the driver code to demarcate critical sections.

Specified by:

recordTime in class DriverContext

Throws:

IllegalStateException - if the operation uses auto timing

pauseTime

public 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. Calls pauseTime when the critical section is already paused are simply ignored.

Specified by:

pauseTime in class DriverContext

getTime

public 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.

Specified by:

getTime in class DriverContext

Returns:

The relative time of the benchmark run

wakeupAt

public void wakeupAt(long time)

Wakes up closest to a system nanosec time.

Parameters:

time - The time to wake up

getSteadyStateStart

public 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.

Specified by:

getSteadyStateStart in class DriverContext

Returns:

The relative time steady state starts

getNanoTime

public 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.

Specified by:

getNanoTime in class DriverContext

Returns:

The relative time of the benchmark run

getSteadyStateStartNanos

public 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.

Specified by:

getSteadyStateStartNanos in class DriverContext

Returns:

The relative time steady state starts

getRampUp

public int getRampUp()

Obtains the configured ramp up time.

Specified by:

getRampUp in class DriverContext

Returns:

The configured ramp up time, in seconds

getSteadyState

public int getSteadyState()

Obtains the configured steady state time.

Specified by:

getSteadyState in class DriverContext

Returns:

The configured steady state time, in seconds

getRampDown

public int getRampDown()

Obtains the configured ramp down time.

Specified by:

getRampDown in class DriverContext

Returns:

The configured ramp down time, in seconds

isPauseSupported

public boolean isPauseSupported()

Property whether pause is supported with the current protocol. Default is true. Protocols that may not be request/response but may have concurrent inbound and outbound traffic, AND wishes to support auto timing should set this flag to false. The default is true.

Returns:

The current setting of the pauseSupported property.

setPauseSupported

public void setPauseSupported(boolean pause)

Property whether pause is supported with the current protocol. Default is true. Protocols that may not be request/response but may have concurrent inbound and outbound traffic, AND wishes to support auto timing should set this flag to false. The default is true.

Parameters:

pause - The new setting of the pauseSupported property.

recordStartTime

public long recordStartTime()

Records the start time of an operation. This method is not exposed through the interface and is only used by the transport facilities.

Returns:

The recorded time - system nanotime, or TIME_NOT_SET if not set

recordEndTime

public long recordEndTime()

Records the end time of an operation. This method is not exposed through the interface and is only used by the transport facilities.

Returns:

The recorded time - system nanotime, or TIME_NOT_SET if not set

getBaseDir

public String getBaseDir()

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

Specified by:

getBaseDir in class DriverContext

Returns:

The benchmark's base directory

getResourceDir

public String getResourceDir()

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

Specified by:

getResourceDir in class DriverContext

Returns:

The resource directory for this benchmark

setUploadSpeed

public void setUploadSpeed(int kbps)

Set the desired upload speed for the thread using this context. This method is intended for use only by transport classes; drivers should call an apporpriate method on the transport to set this value. Note that not all transports support bandwidth throttling (so drivers that do call this method will have no idea if the value is used or not).

Parameters:

kbps - desired speed in kilobytes per second. If kbps is < 0, speed will be unlimited.

getUploadSpeed

public int getUploadSpeed()

Return the desired upload speed for the thread using this context.

Returns:

desired speed in kilobytes per second

setDownloadSpeed

public void setDownloadSpeed(int kbps)

Set the desired downoad speed for the thread using this context. This method is intended for use only by transport classes; drivers should call an apporpriate method on the transport to set this value. Note that not all transports support bandwidth throttling (so drivers that do call this method will have no idea if the value is used or not).

Parameters:

kbps - desired speed in kilobytes per second. If kbps is < 0, speed will be unlimited.

getDownloadSpeed

public int getDownloadSpeed()

Return the desired download speed for the thread using this context.

Returns:

desired speed in kilobytes per second