/* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* http://www.sun.com/cddl/cddl.html or
* install_dir/legal/LICENSE
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at install_dir/legal/LICENSE.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* $Id$
*
* Copyright 2005-2009 Sun Microsystems Inc. All Rights Reserved
*/
package com.sun.faban.driver;
import com.sun.faban.driver.util.Random;
import com.sun.faban.driver.engine.NullContext;
import java.util.logging.Logger;
import org.w3c.dom.Element;
import javax.xml.xpath.XPathExpressionException;
/**
* DriverContext is the point of communication between the
* developer-provided driver and the Faban driver framework.
* Each thread has it's own context.<p>
* The only concrete implementation of this abstract class
* is in com.sun.faban.driver.engine.DriverContext.
*
* @author Akara Sucharitakul
*/
public abstract class DriverContext {
/**
* Obtains the DriverContext associated with this thread.
* @return the associated DriverContext
*/
public static DriverContext getContext() {
DriverContext ctx =
com.sun.faban.driver.engine.DriverContext.getContext();
if (ctx != null)
return ctx;
return new NullContext();
}
/**
* Obtains the scale or scaling rate of the current run.
* @return the current run's scaling rate
*/
public abstract int getScale();
/**
* Obtains the number of client threads in this agent.
*
* @return the number of client threads for this agent
*/
public abstract int getClientsInAgent();
/**
* Obtains the total number of clients threads for this driver.
* @return the number of client threads for this driver
*/
public abstract int getClientsInDriver();
/**
* Obtains the global agent thread id for this context's thread.
* @return the global agent thread id
*/
public abstract int getThreadId();
/**
* Obtains the agent id for this agent.
* @return the current agent's id
*/
public abstract int getAgentId();
/**
* Obtains the driver's name as annotated in the driver class.
* @return the driver name
*/
public abstract String getDriverName();
/**
* Obtains the logger to be used by the calling driver.
* @return the appropriate logger
*/
public abstract Logger getLogger();
/**
* 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.
* @param metrics The custom metrics to be replaced
*/
public abstract void attachMetrics(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.
* @param name The name or description of this metrics
* @param metrics The custom metrics to be replaced
*/
public abstract void attachMetrics(String name, CustomMetrics 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.
* @param name The name or description of this metrics
* @param metrics The custom table metrics to be replaced
*/
public abstract void attachMetrics(String name, CustomTableMetrics metrics);
/**
* Obtains the name of the operation currently executing.
* @return the current operation's name
*/
public abstract String getCurrentOperation();
/**
* 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.
* @return The unique id assigned to this operation type.
*/
public abstract int getOperationId();
/**
* Obtains the number of operations active in this driver.
* @return The number of active operations
*/
public abstract int getOperationCount();
/**
* Obtains the per-thread random value generator. Drivers
* should use this random value generator and not instantiate
* their own.
* @return The random value generator
*/
public abstract Random getRandom();
/**
* 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.
* @return True if in steady state, false if not.
*/
public abstract boolean isTxSteadyState();
/**
* 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.
*/
public abstract void resetMix();
/**
* 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
*/
public abstract void recordTime();
/**
* 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.
*/
public abstract void pauseTime();
/**
* 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.
* @return The relative time of the benchmark run
*/
public abstract int getTime();
/**
* Obtains the relative time - in milliseconds - that steady state starts,
* if set. The if the time is not yet set, it will return 0.
* @return The relative time steady state starts
*/
public abstract int getSteadyStateStart();
/**
* 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.
* @return The relative time of the benchmark run
*/
public abstract long getNanoTime();
/**
* Obtains the relative time - in nanosecs - that steady state starts,
* if set. The if the time is not yet set, it will return 0.
* @return The relative time steady state starts
*/
public abstract long getSteadyStateStartNanos();
/**
* Obtains the configured ramp up time.
* @return The configured ramp up time, in seconds
*/
public abstract int getRampUp();
/**
* Obtains the configured steady state time.
* @return The configured steady state time, in seconds
*/
public abstract int getSteadyState();
/**
* Obtains the configured ramp down time.
* @return The configured ramp down time, in seconds
*/
public abstract int getRampDown();
/**
* 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.
* @param name The property name
* @return The property value
*/
public abstract String getProperty(String name);
/**
* Obtains a multiple-value property from the configuration. A
* single-value property will be returned as an array of dimension 1.
* @param name The property name
* @return The property values
*/
public abstract String[] getPropertyValues(String name);
/**
* 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.
* @return The DOM tree representing the properties node
*/
public abstract Element getPropertiesNode();
/**
* Reads the element or attribute by it's XPath. The XPath is evaluated
* from the root of the configuration file.
* @param xPath The XPath to evaluate.
* @return The element or attribute value defined by the XPath
* @exception XPathExpressionException If the given XPath has an error
*/
public abstract String getXPathValue(String xPath)
throws XPathExpressionException;
/**
* Obtains the base directory where the benchmark currently being run
* is installed.
* @return The benchmark's base directory
*/
public abstract String getBaseDir();
/**
* Obtains the resource directory used for this benchmark, if exists.
* @return The resource directory for this benchmark
*/
public abstract String getResourceDir();
}