Package com.xceptance.xlt.api.engine

# Class Session

java.lang.Object
com.xceptance.xlt.api.engine.Session

public abstract class Session extends Object
The `Session` object is the runtime context during one run of a certain test case.

Multiple threads running the same test case will get different sessions. A session is the anchor that holds the data recorded during that very test run.

ATTENTION: A session can be reused across different test runs if and only if it is cleared before its reuse.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Session()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `addShutdownListener(SessionShutdownListener listener)`
  Registers the passed shutdown listener to be called on session termination.
  `abstract void`
  `clear()`
  Clears the session.
  `abstract int`
  `getAbsoluteUserNumber()`
  Returns the number of the currently running test user.
  `abstract String`
  `getAgentID()`
  Returns the ID of the current agent.
  `abstract int`
  `getAgentNumber()`
  Returns the number (or index) of the current agent.
  `static Session`
  `getCurrent()`
  Returns the thread-specific Session instance.
  `abstract String`
  `getCurrentActionName()`
  Returns the name of the current action as specified when the action was started.
  `abstract DataManager`
  `getDataManager()`
  Returns the session's data manager.
  `abstract String`
  `getID()`
  Returns the session's ID.
  `abstract NetworkDataManager`
  `getNetworkDataManager()`
  Returns the network data manager.
  `abstract Path`
  `getResultsDirectory()`
  Returns the session's results directory.
  `abstract String`
  `getTestCaseClassName()`
  Returns the fully qualified class name of the test case to which this session belongs.
  `abstract int`
  `getTotalAgentCount()`
  Returns the total count of agents that take part in a load test.
  `abstract int`
  `getTotalUserCount()`
  Returns the total count of test users running during a test.
  `abstract int`
  `getUserCount()`
  Returns the total count of the test users with the same type as the current user, for example "35".
  `abstract String`
  `getUserID()`
  Returns the ID of the currently running test user, for example "TAddToCart-27".
  `abstract String`
  `getUserName()`
  Returns the name of the currently running test user, for example "TAddToCart".
  `abstract int`
  `getUserNumber()`
  Returns the instance number of the currently running test user, for example "27".
  `abstract Map<String,Object>`
  `getValueLog()`
  Returns this session's value log, a storage for session-specific test parameters and result data.
  `abstract String`
  `getWebDriverActionName()`
  Deprecated.
  As of XLT 4.6.0, use `getCurrentActionName()` instead.
  `abstract boolean`
  `hasFailed()`
  Returns the session's failure status.
  `abstract boolean`
  `isLoadTest()`
  Indicates whether the current test session is executed in the context of a functional test or a load test.
  `static final void`
  `logData(String scope, String lineOfData)`
  Logs a line of custom data in the datalogger of the given scope.
  `static final void`
  `logEvent(String eventName, String eventMessage)`
  Logs an event.
  `abstract void`
  `removeShutdownListener(SessionShutdownListener listener)`
  Unregisters the passed shutdown listener.
  `abstract void`
  `setFailed()`
  Sets the session's failure status to failed.
  `abstract void`
  `setFailed(boolean value)`
  Sets the session's failure status.
  `abstract void`
  `setID(String id)`
  Sets the session's ID.
  `abstract void`
  `setNotFailed()`
  Unsets the session failure state.
  `abstract void`
  `setWebDriverActionName(String webDriverActionName)`
  Deprecated.
  As of XLT 4.6.0, use `startAction(String)` instead.
  `abstract void`
  `startAction(String actionName)`
  Tells the framework to start a new action with the given name.
  `abstract void`
  `stopAction()`
  Tells the framework to finish the current action.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### Session

    public Session()

- ## Method Details

  - ### getCurrent

    public static Session getCurrent()
    Returns the thread-specific Session instance. If no such instance exists yet, it will be created.
    Returns:
      the Session instance for the current thread

  - ### logEvent

    public static final void logEvent(String eventName, String eventMessage)
    Logs an event.
    Parameters:
      `eventName` - name of the event
      `eventMessage` - the event message

  - ### logData

    public static final void logData(String scope, String lineOfData)
    Logs a line of custom data in the datalogger of the given scope. (Shortcut method for getDataManager().dataLogger(scope).log(lineOfData))
    Parameters:
      `scope` - scope of the data logger to be used
      `lineOfData` - line of data to be logged

  - ### addShutdownListener

    public abstract void addShutdownListener(SessionShutdownListener listener)
    Registers the passed shutdown listener to be called on session termination.
    Parameters:
      `listener` - the shutdown listener

  - ### clear

    public abstract void clear()
    Clears the session. All state is removed. This includes the request history as well.

  - ### getAbsoluteUserNumber

    public abstract int getAbsoluteUserNumber()
    Returns the number of the currently running test user. This value ranges from 0...(n-1), where n denotes the total number of configured test users, independent of their respective user type.
    Returns:
      the test user's absolute instance number

  - ### getAgentID

    public abstract String getAgentID()
    Returns the ID of the current agent.
    Returns:
      the agent's ID

  - ### getAgentNumber

    public abstract int getAgentNumber()
    Returns the number (or index) of the current agent. This value ranges from 0...(n-1), where n denotes the total number of configured agents.
    Returns:
      the agent's instance number

  - ### getID

    public abstract String getID()
    Returns the session's ID.
    Returns:
      the session ID

  - ### getTestCaseClassName

    public abstract String getTestCaseClassName()
    Returns the fully qualified class name of the test case to which this session belongs.
    Returns:
      the test class name
    Since:
      7.0.0

  - ### getDataManager

    public abstract DataManager getDataManager()
    Returns the session's data manager.
    Returns:
      the data manager

  - ### getTotalAgentCount

    public abstract int getTotalAgentCount()
    Returns the total count of agents that take part in a load test.
    Returns:
      the total count

  - ### getTotalUserCount

    public abstract int getTotalUserCount()
    Returns the total count of test users running during a test. This includes all users of all types.
    Returns:
      the total count of users

  - ### getUserCount

    public abstract int getUserCount()
    Returns the total count of the test users with the same type as the current user, for example "35".
    Returns:
      the total count

  - ### getUserID

    public abstract String getUserID()
    Returns the ID of the currently running test user, for example "TAddToCart-27".
    Returns:
      the test user's ID

  - ### getUserName

    public abstract String getUserName()
    Returns the name of the currently running test user, for example "TAddToCart".
    Returns:
      the test user's name

  - ### getUserNumber

    public abstract int getUserNumber()
    Returns the instance number of the currently running test user, for example "27". This value ranges from 0...(n-1), where n denotes the total number of configured test users with the same type as the current test user.
    Returns:
      the test user's instance number

  - ### hasFailed

    public abstract boolean hasFailed()
    Returns the session's failure status.
    Returns:
      whether or not the session has failed

  - ### isLoadTest

    public abstract boolean isLoadTest()
    Indicates whether the current test session is executed in the context of a functional test or a load test.
    Returns:
      `true` if we are in the middle of a load test, `false` otherwise

  - ### getResultsDirectory

    public abstract Path getResultsDirectory()
    Returns the session's results directory.
    Returns:
      the result directory

  - ### removeShutdownListener

    public abstract void removeShutdownListener(SessionShutdownListener listener)
    Unregisters the passed shutdown listener.
    Parameters:
      `listener` - the shutdown listener

  - ### setFailed

    public abstract void setFailed(boolean value)
    Sets the session's failure status.
    Parameters:
      `value` - whether or not the session has failed

  - ### setFailed

    public abstract void setFailed()
    Sets the session's failure status to failed.

  - ### setNotFailed

    public abstract void setNotFailed()
    Unsets the session failure state.

  - ### setID

    public abstract void setID(String id)
    Sets the session's ID.
    Parameters:
      `id` - the new session ID

  - ### getNetworkDataManager

    public abstract NetworkDataManager getNetworkDataManager()
    Returns the network data manager.
    Returns:
      network data manager

  - ### getWebDriverActionName

    @Deprecated public abstract String getWebDriverActionName()
    Deprecated.
    As of XLT 4.6.0, use `getCurrentActionName()` instead.

  - ### setWebDriverActionName

    @Deprecated public abstract void setWebDriverActionName(String webDriverActionName)
    Deprecated.
    As of XLT 4.6.0, use `startAction(String)` instead.

  - ### startAction

    public abstract void startAction(String actionName)
    Tells the framework to start a new action with the given name. If there is still a pending (i.e. unfinished) action, then this action will be finished before the new action is started.

    Note that calling this method is not necessary for test cases that automatically manage the action life cycle. This includes test cases that are built with action classes, but also interpreted or exported script test cases. You would need to call this method for plain WebDriver-based or plain HtmlUnit-based test cases, though.

    Parameters:
      `actionName` - the name of the new action
    See Also:
      - `stopAction()`
      - `AbstractAction`

  - ### stopAction

    public abstract void stopAction()
    Tells the framework to finish the current action. If there is no pending action, calling this method has no effect.

    Finishing an action includes logging the action's run time and result. Whether the action is logged as successful or failed depends on the session's failed state.

    See Also:
      - `setFailed(boolean)`
      - `startAction(String)`

  - ### getCurrentActionName

    public abstract String getCurrentActionName()
    Returns the name of the current action as specified when the action was started. When called between two actions (i.e. after finishing the previous action, but before starting a new one), the returned action name will be `null`.
    Returns:
      the name of the current action, or `null` if there is none
    See Also:
      - `startAction(String)`

  - ### getValueLog

    public abstract Map<String,Object> getValueLog()
    Returns this session's value log, a storage for session-specific test parameters and result data. Any value you add to this log will later be available in the result browser. Note that the log will be cleared with each new iteration.

    This feature is intended to aid in error analysis. The data in the result browser may help you to reconstruct and rerun a failed test case iteration without having to dig into log files. Simply add any value of special interest and you will have it at hand in the result browser. This is especially useful if your test case uses random or randomly chosen test parameters.

    Data is stored as name/value pairs. Even though the log accepts any `Object` as the value, the value will later be converted to a string using `Object.toString()` for proper display in the result browser. So make sure your value classes implement this method appropriately.

    Returns:
      the values keyed by their names