Callback Actions

A callback specifies a class that will be called for each matching request and can be used to dynamically generate the response.

Callback actions contain:

• callbackClass

The callback class must:

• have a default constructor
• implement org.mockserver.mock.action.ExpectationCallback
• be available on the classpath (see below)

Callback actions can be further controlled using:

• the number of times the callback is called (including unlimited)
• a time to live the callback will be continued to be called (including unlimited)

If MockServer is started using the JUnitRule org.mockserver.junit.MockServerRule or using org.mockserver.integration.ClientAndServer or directly using the org.mockserver.mockserver.MockServerBuilder then any class present in the main or test classpaths will be visible to MockServer.

If MockServer is started using the plugin only the non-forked goals (such as runAndWait and start) will be able to load classes from the main and test classpaths. It is possible to use classes from a separate maven dependency, however, this dependency must be specified in the plugin configuration dependencies section. Any dependency added to the plugin configuration dependencies section will then be visible to MockServer run using both forked and non-forked goals.

The following configuration shows how to use classes from a separate maven dependency in callback actions.

 <plugin>
     <groupId>org.mock-server</groupId>
     <artifactId>mockserver-maven-plugin</artifactId>
     <version>4.0.0</version>
     <configuration>
        <serverPort>1080</serverPort>
        <logLevel>DEBUG</logLevel>
        <pipeLogToConsole>true</pipeLogToConsole>
     </configuration>
     <executions>
         <execution>
             <id>pre-integration-test</id>
             <phase>pre-integration-test</phase>
             <goals>
                 <goal>runForked</goal>
             </goals>
         </execution>
         <execution>
             <id>post-integration-test</id>
             <phase>post-integration-test</phase>
             <goals>
                 <goal>stopForked</goal>
             </goals>
         </execution>
     </executions>
     <dependencies>
         <dependency>
             <groupId>com.my-domain</groupId>
             <artifactId>my-callback-dependency</artifactId>
             <version>1.0.0</version>
         </dependency>
     </dependencies>
 </plugin>

If MockServer is started using the command line then the callback classes must be added to the JVM using the classpath command line switch (cp or classpath). The classpath switch is ignored by the JVM if the jar switch is used. So to run the MockServer from the command line directly (with mockserver-netty-4.0.0-jar-with-dependencies.jar) you must specify the org.mockserver.cli.Main main class specifically and not use the jar switch as follows.

java -Dfile.encoding=UTF-8 -cp mockserver-netty-4.0.0-jar-with-dependencies.jar:my-callback-dependency.jar org.mockserver.cli.Main -serverPort 1080

Java

When mocking a callback in Java use the org.mockserver.model.HttpClassCallback class which specifies the details class to callback as follows, for example:

HttpCallback httpClassCallback = callback("org.some.package.MyCallback");

The full specification of org.mockserver.model.HttpClassCallback is as follows:

public class HttpCallback {

    /**
     * The class to callback as a fully qualified class name
     *
     * This calls must:
     *  - implement org.mockserver.mock.action.ExpectationCallback
     *  - have a zero argument constructor
     *  - be available in the classpath of the MockServer
     *
     * @param callbackClass class to callback as a fully qualified class name, i.e. "com.foo.MyExpectationCallback"
     */
    public HttpCallback withCallbackClass(String callbackClass);

}

The class specified must implement the org.mockserver.mock.action.ExpectationCallback interface as follows:

public interface ExpectationCallback {

    /**
     * Called for every request when expectation condition has been satisfied.
     * The request that satisfied the expectation condition is passed as the
     * parameter and the return value is the response that will be returned to the client.
     *
     * @param httpRequest the request that satisfied the expectation condition
     * @return the response that will be returned to the client
     */
    public HttpResponse handle(HttpRequest httpRequest);

}

Times

The org.mockserver.matchers.Times class is used to specify how many times you want MockServer to match a request:

To create an instance of Times use one of the static factory methods:

Times.unlimited();
Times.once();
Times.exactly(int count);

JavaScript

To setup a callback in javascript use JSON to specify the details with the following format:

"httpClassCallback": {
    "callbackClass": "org.mypackage.MyCallbackClass"
}