BackendListenerClient (Apache JMeter dist API)
Description: declaration: package: org.apache.jmeter.visualizers.backend, interface: BackendListenerClient

Package org.apache.jmeter.visualizers.backend

# Interface BackendListenerClient

All Known Implementing Classes:
  `AbstractBackendListenerClient`, `GraphiteBackendListenerClient`, `InfluxdbBackendListenerClient`, `InfluxDBRawBackendListenerClient`

public interface BackendListenerClient
This interface defines the interactions between the `BackendListener` and external Java programs which can be executed by JMeter. Any Java class which wants to be executed using the `BackendListener` test element must implement this interface (either directly or through `AbstractBackendListenerClient`).

JMeter will create one instance of a BackendListenerClient implementation for each user/thread in the test. Additional instances may be created for internal use by JMeter (for example, to find out what parameters are supported by the client).

When the test is started, setupTest() will be called on each thread's BackendListenerClient instance to initialize the client. Then `handleSampleResults(List, BackendListenerContext)` will be called for each `SampleResult` notification. Finally, `teardownTest(BackendListenerContext)` will be called to allow the client to do any necessary clean-up.

The JMeter BackendListener GUI allows a list of parameters to be defined for the test. These are passed to the various test methods through the `BackendListenerContext`. A list of default parameters can be defined through the `getDefaultParameters()` method. These parameters and any default values associated with them will be shown in the GUI. Users can add other parameters as well.

Listeners should extend `AbstractBackendListenerClient` rather than implementing `BackendListenerClient` directly to protect your code from future changes to the interface.

While it may be necessary to make changes to the `BackendListenerClient` interface from time to time (therefore requiring changes to any implementations of this interface), we intend to make this abstract class provide reasonable default implementations of any new methods so that subclasses do not necessarily need to be updated for new versions. Implementing BackendListenerClient directly will continue to be supported for cases where extending this class is not possible (for example, when the client class is already a subclass of some other class).

Since:
  2.13

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default SampleResult`
  `createSampleResult(BackendListenerContext context, SampleResult result)`
  Create a copy of SampleResult, this method is here to allow customizing what is kept in the copy, for example copy could remove some useless fields.
  `default Arguments`
  `getDefaultParameters()`
  Provide a list of parameters which this test supports.
  `void`
  `handleSampleResults(List<SampleResult> sampleResults, BackendListenerContext context)`
  Handle sampleResults, this can be done in many ways: Write to a file Write to a remote server ...
  `void`
  `setupTest(BackendListenerContext context)`
  Do any initialization required by this client.
  `void`
  `teardownTest(BackendListenerContext context)`
  Do any clean-up required at the end of a test run.

- ## Method Details

  - ### setupTest

    void setupTest(BackendListenerContext context) throws Exception
    Do any initialization required by this client. It is generally recommended to do any initialization such as getting parameter values here rather than `handleSampleResults(List, BackendListenerContext)` in order to add as little overhead as possible to the test.
    Parameters:
      `context` - provides access to initialization parameters.
    Throws:
      `Exception` - when setup fails

  - ### handleSampleResults

    void handleSampleResults(List<SampleResult> sampleResults, BackendListenerContext context)
    Handle sampleResults, this can be done in many ways:
    - Write to a file
    - Write to a remote server
    - ...
    Parameters:
      `sampleResults` - List of `SampleResult`
      `context` - provides access to initialization parameters.

  - ### teardownTest

    void teardownTest(BackendListenerContext context) throws Exception
    Do any clean-up required at the end of a test run.
    Parameters:
      `context` - provides access to initialization parameters.
    Throws:
      `Exception` - when tear down fails

  - ### getDefaultParameters

    default Arguments getDefaultParameters()
    Provide a list of parameters which this test supports. Any parameter names and associated values returned by this method will appear in the GUI by default so the user doesn't have to remember the exact names. The user can add other parameters which are not listed here. If this method returns null then no parameters will be listed. If the value for some parameter is null then that parameter will be listed in the GUI with an empty value.
    Returns:
      a specification of the parameters used by this test which should be listed in the GUI, or null if no parameters should be listed.

  - ### createSampleResult

    default SampleResult createSampleResult(BackendListenerContext context, SampleResult result)
    Create a copy of SampleResult, this method is here to allow customizing what is kept in the copy, for example copy could remove some useless fields. Note that if it returns null, the sample result is not put in the queue. Defaults to returning result.
    Parameters:
      `context` - `BackendListenerContext`
      `result` - `SampleResult`
    Returns:
      `SampleResult`