Martini Invoking Services via a HTTP Filter Trigger

The HTTP filter trigger in Martini allows developers to conditionally invoke services based on the characteristics of incoming HTTP requests. This functionality enables the execution of specific services only when the incoming request satisfies predefined conditions set in the HTTP filter trigger's configuration. Requests that do not meet these conditions are ignored, and the associated service is not activated.

Martini integrates this feature by registering a filter for each HTTP filter trigger, utilizing Java's standard mechanisms for filtering requests and responses.

Properties

The configuration of an HTTP filter trigger includes both general properties applicable to all triggers and specific settings unique to the HTTP filter trigger.

HTTP Filter-Specific Configuration

Below are the properties specific to HTTP filter triggers:

Property	Default	Description
Priority	2147483647	Determines the execution order among HTTP filter triggers with the same filter order. A lower number indicates a higher priority.
Filter order	(required)	Specifies the phase during which Martini should authenticate the request relative to the filter's execution.
Path pattern type	(required)	Defines the type of path patterns (glob pattern or regular expression pattern) to match against incoming requests.
Path patterns	(required)	A set of request path patterns that incoming requests must match to trigger the configured service.
Case sensitive	true	Indicates if path pattern matching should consider case sensitivity.
Request methods	(required)	Lists the HTTP methods an incoming request must use to qualify for triggering the configured service.

Service Parameters

HTTP filter triggers support specific parameters that provide detailed context about the matching request and allow for comprehensive control over the request-response process.

HTTP Filter-Specific Parameters

Name	Type	Description
$__request	javax.servlet.http.HttpServletRequest	The HttpServletRequest object for the incoming request.
$__response	javax.servlet.http.HttpServletResponse	The HttpServletResponse object paired with the request.
$__chain	javax.servlet.FilterChain	Controls the continuation or termination of the filter chain.
uri	java.lang.String	The URI of the incoming request.
url	java.lang.String	The full URL of the request.
method	java.lang.String	The HTTP method used by the request.
user	java.security.Principal	The authenticated user for the request, applicable only in certain contexts.

Return Values

Services linked with HTTP filter triggers can specify return values to alter the behavior of the filter chain.

Name	Type	Description
$__newRequest	javax.servlet.http.HttpServletRequest	Substitutes the original request with a new one for subsequent filters.
$__newResponse	javax.servlet.http.HttpServletResponse	Substitutes the original response with a new one for subsequent filters.
$__discontinueChain	boolean	Determines whether to halt the filter chain. A value of true signifies that Martini assumes the service will handle the invocation of subsequent filters manually.

Notes and Tips

• The registration of the filter corresponding to a trigger is managed by Martini and occurs upon the trigger's activation, with deregistration upon deactivation.

Example: Groovy Method as Service

This Groovy example demonstrates how to manipulate HTTP response headers by injecting 'X'-prefixed request headers into the response, converting their values to uppercase:

import javax.servlet.http.HttpServletRequest
import javax.servlet.http.HttpServletResponse
import javax.servlet.http.HttpServletResponseWrapper

class HttpFilterExamples {

    /**
     * Alters the response to include 'X'-prefixed request headers as response headers,
     * transforming their values to uppercase.
     *
     * @param $__request the matched request
     * @param $__response the response for the matched request
     * @return an altered response object
     */
    static HttpServletResponse toUppercaseXPrefixedHeaders(
        HttpServletRequest $__request, HttpServletResponse $__response ) {

        HttpServletResponseWrapper responseWrapper = new HttpServletResponseWrapper($__response);
        Enumeration<String> headers = $__request.getHeaderNames();
        while (headers.hasMoreElements()) {
            String header = headers.nextElement();
            if (header.toUpperCase().startsWith("X-")) {
                Enumeration<String> values = $__request.getHeaders(header);
                while (values.hasMoreElements()) {
                    String value = values.nextElement();
                    responseWrapper.addHeader(header, value.toUpperCase());
                }
            }
        }

        return responseWrapper;
    }
}

This method intercepts the incoming HTTP request, checks for headers that start with 'X-', and re-injects them into the response with their values converted to uppercase. This example illustrates how HTTP filter triggers can be leveraged for dynamic request/response manipulation in Martini, showcasing the platform's flexibility in integrating custom logic within HTTP workflows.