diff --git a/_docs/extending-wiremock.md b/_docs/extending-wiremock.md index 5b3c4fde..180176e0 100644 --- a/_docs/extending-wiremock.md +++ b/_docs/extending-wiremock.md @@ -1,6 +1,6 @@ --- layout: docs -title: Extending WireMock - Overview +title: Extending WireMock meta_title: Extending WireMock via custom code | WireMock toc_rank: 110 redirect_from: "/extending-wiremock.html" @@ -13,15 +13,15 @@ Each extension point is defined by an interface that extends from `Extension` an At present, the following extension interfaces are available: * `RequestFilterV2`/`AdminRequestFilterV2`/`StubRequestFilterV2`: Intercept requests, modifying them or taking alternative actions based on their content. -* `ResponseDefinitionTransformerV2`: Modify the response definition used to generate a response. See [Transforming responses](extensibility/transforming-responses/). -* `ResponseTransformerV2`: Modify the response served to the client. See [Transforming responses](extensibility/transforming-responses/). -* `ServeEventListener`: Listen for events at various points in the request processing lifecycle. See [Transforming responses](extensibility/listening-for-serve-events/). -* `AdminApiExtension`: Add admin API functions. See [Transforming responses](extensibility/extending-the-admin-api/). -* `RequestMatcherExtension`: Implement custom request matching logic. See [Transforming responses](extensibility/custom-matching/). -* `GlobalSettingsListener`: Listen for changes to the settings object. See [Transforming responses](extensibility/listening-for-settings-changes/). -* `StubLifecycleListener`: Listen for changes to the stub mappings. See [Transforming responses](extensibility/listening-for-stub-changes/). -* `TemplateHelperProviderExtension`: Provide custom Handlebars helpers to the template engine. See [Transforming responses](extensibility/adding-template-helpers/). -* `TemplateModelDataProviderExtension`: Provide additional data to the model passed to response templates. See [Transforming responses](extensibility/adding-template-model-data/). +* `ResponseDefinitionTransformerV2`: Modify the response definition used to generate a response. See [Transforming responses](../extensibility/transforming-responses/). +* `ResponseTransformerV2`: Modify the response served to the client. See [Transforming responses](../extensibility/transforming-responses/). +* `ServeEventListener`: Listen for events at various points in the request processing lifecycle. See [Listening for Serve Events](../extensibility/listening-for-serve-events/). +* `AdminApiExtension`: Add admin API functions. See [Admin API Extensions](../extensibility/extending-the-admin-api/). +* `RequestMatcherExtension`: Implement custom request matching logic. See [Custom matching](../extensibility/custom-matching/). +* `GlobalSettingsListener`: Listen for changes to the settings object. See [Listening for Settings Changes](../extensibility/listening-for-settings-changes/). +* `StubLifecycleListener`: Listen for changes to the stub mappings. See [Listening for Stub Changes](../extensibility/listening-for-stub-changes/). +* `TemplateHelperProviderExtension`: Provide custom Handlebars helpers to the template engine. See [Adding Template Helpers](../extensibility/adding-template-helpers/). +* `TemplateModelDataProviderExtension`: Provide additional data to the model passed to response templates. See [Adding Template Model Data](../extensibility/adding-template-model-data/). The interfaces in this list ending with `V2` supercede deprecated equivalents with an older, more restrictive interface. Additionally `ServeEventListener` deprecates `PostServeAction`. @@ -87,7 +87,10 @@ Several types of extension act on WireMock's request processing: `RequestFilterV The primary method in each of these takes the current `ServeEvent` as a parameter and sub-events can be attached to this: ```java -serveEvent.appendSubEvent("JSON_PARSE_WARNING", Map.of("message", "Single quotes are not permitted")); +serveEvent.appendSubEvent( + "JSON_PARSE_WARNING", + Map.of("message", "Single quotes are not permitted") +); ``` The second parameter to `appendSubEvent()` can be a Map or object containing any data required. \ No newline at end of file diff --git a/_docs/extensibility/listening-for-serve-events.md b/_docs/extensibility/listening-for-serve-events.md index 76437221..eacc08dc 100644 --- a/_docs/extensibility/listening-for-serve-events.md +++ b/_docs/extensibility/listening-for-serve-events.md @@ -11,4 +11,57 @@ The `ServeEventListener` interface (which deprecates `PostServeAction`) supports ## Listening for specific lifecycle events -TODO \ No newline at end of file +The `ServeEventListener` interface has a set of callback methods that can be implemented for specific points in the request lifecycle. These have no-op defaults, so you can override just the ones that are relevant: + +```java +public class MyServeEventListener implements ServeEventListener { + + @Override + public void beforeMatch(ServeEvent serveEvent, Parameters parameters) { + // Do something before request matching + } + + @Override + public void afterMatch(ServeEvent serveEvent, Parameters parameters) { + // Do something after request matching + } + + @Override + public void beforeResponseSent(ServeEvent serveEvent, Parameters parameters) { + // Do something before the response is sent to the client + } + + @Override + public void afterComplete(ServeEvent serveEvent, Parameters parameters) { + // Do something after the response has been sent to the client + } + + @Override + public String getName() { + return "my-listener"; + } +} +``` + +## Listening for all lifecycle events + +The alternative approach you can take is to listen for all events along with a request phase value indicating when the event fired: + +```java +public class MyServeEventListener implements ServeEventListener { + + @Override + public void onEvent( + RequestPhase requestPhase, + ServeEvent serveEvent, + Parameters parameters) { + + log.debug("Received serve event in phase " + requestPhase); + } + + @Override + public String getName() { + return "my-listener"; + } +} +``` \ No newline at end of file diff --git a/_docs/extensibility/listening-for-settings-changes.md b/_docs/extensibility/listening-for-settings-changes.md index 78da714b..56cb99f1 100644 --- a/_docs/extensibility/listening-for-settings-changes.md +++ b/_docs/extensibility/listening-for-settings-changes.md @@ -5,4 +5,38 @@ meta_title: Listening for Settings Changes description: Listening for Settings Changes --- -TODO \ No newline at end of file +You can listen for changes to the global settings object. + +This is most useful when combined with other extension points, allowing extensions to define and make use of extended settings values rather than rolling their own configuration strategy. + +A common pattern is to listen for changes and capture the value locally, using this to affect the main extension's behaviour e.g.: + +```java +public class MyConfigurableServeEventListener + implements ServeEventListener, GlobalSettingsListener { + + private volatile String mySetting = ""; + + @Override + public void afterGlobalSettingsUpdated( + GlobalSettings oldSettings, + GlobalSettings newSettings) { + + mySetting = newSettings.getExtended().getString("my-setting"); + } + + @Override + public void onEvent( + RequestPhase requestPhase, + ServeEvent serveEvent, + Parameters parameters) { + + log.debug("My setting is " + mySetting); + } + + @Override + public String getName() { + return "my-listener"; + } +} +``` \ No newline at end of file diff --git a/_docs/extensibility/listening-for-stub-changes.md b/_docs/extensibility/listening-for-stub-changes.md index aef7035f..663deef4 100644 --- a/_docs/extensibility/listening-for-stub-changes.md +++ b/_docs/extensibility/listening-for-stub-changes.md @@ -5,4 +5,34 @@ meta_title: Listening for Stub Changes description: Listening for Stub Changes --- -TODO \ No newline at end of file +You can subscribe to changes in the state of WireMock's stubs via the `StubLifecycleListener` extension point. + +For instance, to respond after a new stub has been created you would do the following: + +```java +public class MyStubEventListener implements StubLifecycleListener { + + @Override + public void afterStubCreated(StubMapping stub) { + log.debug("Stub named " + stub.getName() + " was created"); + } + + @Override + public String getName() { + return "my-listener"; + } +} +``` + +The following methods can be overridden to subscribe to various stub lifecycle events: + +```java +void beforeStubCreated(StubMapping stub) +void afterStubCreated(StubMapping stub) +void beforeStubEdited(StubMapping oldStub, StubMapping newStub) +void afterStubEdited(StubMapping oldStub, StubMapping newStub) +void beforeStubRemoved(StubMapping stub) +void afterStubRemoved(StubMapping stub) +void beforeStubsReset() +void afterStubsReset() +``` \ No newline at end of file