10.17. Configuring the HTTP Gateway

The HTTP Gateway uses the JBoss Enterprise SOA Platform's Application Server's HTTP Container to expose HTTP end-points, hence many of the configurations are managed at the container level. These are the bind/port address, SSL and so forth.
The following code shows you the way easiest to configure the <http-gateway> on a service (no provider configuration is required):
<service category="Vehicles" name="Cars" description="" invmScope="GLOBAL">
        <http-gateway name="Http" />
    <actions mep="RequestResponse">
        <!-- Service Actions.... -->
The above configuration uses the default HTTP bus provider. This is because it does not define a busrefid attribute. It uses the service category and name to construct the HTTP end-point address of the following format:
The <.esbname> token is the name of the .esb deployment, without the “.esb” extension. Note also the “http” token in the address. This is a hardcoded name-space prefix used for all <http-gateway> end-points.
The <http-gateway> also supports a urlPattern:
<service category="Vehicles" name="Cars" description="" invmScope="GLOBAL">
        <http-gateway name="Http" urlPattern="esb-cars/*" />
    <actions mep="RequestResponse">
        <!-- Service Aactions.... -->
This will expose an HTTP end-point for the service, capturing all HTTP requests found at the following address:
You can use the allowedPorts property to confine certain services to one or more HTTP ports. To do so, create a comma-separated list of the ports in question like this:
<http-gateway name="Http" urlPattern="esb-cars/*">
    <property name="allowedPorts" value="8080,8081">
This will expose a HTTP end-point for the service, capturing all HTTP requests under the following ports only (all other port's request would receive HTTP Status code 404 – Not Found).
  • http://<host>:8080/*
  • http://<host>:8081/*
The <http-gateway> is typically able to decode a HTTP request payload based on the request MIME type. It uses the jbossesb-properties.xml file's “core:org.jboss.soa.esb.mime.text.types” configuration property to decide whether the payload is to be decoded for the service as a string or whether it is to remain as a byte array, with the service handling the decoding itself through an action.
The “core:org.jboss.soa.esb.mime.text.types” configuration property is a semi-colon separated list of “text” (character) MIME types, with the default set being as follows (note the support for wildcards):
  • text/*
  • application/xml
  • application/*-xml
The <http-gateway> uses the character encoding from the request when decoding text payloads.
The <http-gateway> also supports the payloadAs attribute, which can be used as an override for the default MIME type based behavior described above. With this attribute, you can explicitly tell the gateway to treat the payload as “BYTES” or “STRING”.
The HTTP Request contains a lot of other information in addition to the data payload that may be required by the service.  This information is stored, by the gateway, in a HttpRequest object instance on the message.  Use this code inside an action to access that information:
HttpRequest requestInfo = HttpRequest.getRequest(message);
HttpRequest exposes the following set of properties (via getter methods)

Table 10.12. Properties

Property Description
queryParams A java.util.Map<String, String[]> containing the query parameters.  Note the values are String[] so as to support multi-valued parameters.
headers A java.util.List<HttpHeader> containing the request headers.
authType The name of the authentication scheme used to protect the endpoint, or null if not authenticated. Same as the value of the CGI variable AUTH_TYPE.
characterEncoding The name of the character encoding used in the body of this request, or null if the request does not specify a character encoding.
contentType Content Type (MIME Type) of the body of the request, or null if the type is not known.  Same as the value of the CGI variable CONTENT_TYPE.
contextPath The portion of the request URI that indicates the context of the request.  The context path always comes first in a request URI.  The path starts with a "/" character but does not end with a "/" character.  For endpoints in the default (root) context, this returns "".  The container does not decode this string.  (See Servlet Spec.)
pathInfo Any extra path information associated with the URL the client sent when it made this request. The extra path information follows the endpoint path but precedes the query string and will start with a "/" character. This method returns null if there was no extra path information. Same as the value of the CGI variable PATH_INFO. (See Servlet Spec.)
pathInfoToken A List<String> containing the tokens of the pathInfo.
queryString Query String (See Servlet Spec)
requestURI The part of this request URL from the protocol name up to the query string. The web container does not decode this String. (See Servlet Spec)
requestPath The part of this request URL that calls the endpoint. Does not include any additional path information or a query string. Same as the value of the CGI variable SCRIPT_NAME. This method will return just "http") if the urlPattern was "/*". (See Servlet Spec)
localAddr The IP address of the interface on which the request  was received.
localName The host name of the IP interface on which the request was received.
method HTTP Method
protocol Name and version of the HTTP protocol
remoteAddr The IP address of the client or last proxy that sent the request. Same as the value of the CGI variable REMOTE_ADDR.
remoteHost The fully qualified name of the client or the last proxy that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this will be the dotted-string form of the IP address. Same as the value of the CGI variable REMOTE_HOST.
remoteUser The login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated. Whether the username is sent along with each subsequent request depends on the client and type of authentication. Same as the value of the CGI variable REMOTE_USER.
contentLength The length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known. For HTTP servlets, same as the value of the CGI variable CONTENT_LENGTH.
requestSessionId The session ID specified by the client, or null if non specified.
scheme Scheme being used, whether it be “http” or “https.”.
serverName The host name of the server to which the request was sent. It is the value of the part before ":" in the “Host” header value, if any, or the resolved server name, or the server IP address.

By default, this gateway synchronously invokes the associated service and returns the service response payload as the HTTP response.
The HTTP Gateway always returns a synchronous response to a synchronous HTTP client, so it is never asynchronous in the absolute sense of the word.  By default, the Gateway will synchronously invoke the action pipeline, returning the synchronous service response as the HTTP response from the gateway.
Asynchronous response behavior, from the point of view of this Gateway, simply means that the gateway returns a synchronous HTTP response after an asynchronous invocation of the action pipeline (that is, not a synchronous service invocation).  Because it invokes the service asynchronously, it cannot return a service response as part of its synchronous HTTP response.  Therefore, you need to configure the gateway telling it how to make the asynchronous response.
To configure the asynchronous behavior, add an <asyncHttpResponse> element to the <http-gateway>:
    <http-gateway name="Http" urlPattern="esb-cars/*">
        <asyncResponse />
If configured as above, the gateway will return a zero length HTTP response payload, with a HTTP status of 200 (OK).
The asynchronous response HTTP status code can be configured (away from the default of 200) by simply setting the "statusCode" attribute on the <asyncResponse> element:
    <http-gateway name="Http" urlPattern="esb-cars/*">
        <asyncResponse statusCode="202" />
As stated above, a zero length payload is returned (by default) for asynchronous responses.  This can be overridden by specifying a <payload> element on the <asyncResponse> element:
    <http-gateway name="Http" urlPattern="esb-cars/*">
        <asyncResponse statusCode="202">
            <payload classpathResource="/202-static-response.xml"
                     characterEncoding="UTF-8" />

Table 10.13. 

Property Description Required
Specifies the path to a file on the classpath that contains the response payload.
Specifies the content/mime type of the payload data specified by the classpathResource attribute.
The character encoding of the data specified by the classpathResource attribute.

Consistent with how the gateway creates a HttpRequest object instance for the associated service, the associated service can create a HttpResponse object for the gateway on a synchronous HTTP gateway invocation.
Use this code in your service's action to create and set a HttpResponse instance on the response message:
HttpResponse responseInfo = new HttpResponse(HttpServletResponse.SC_OK);
// Set other response info ...
// Set the HttpResponse instance on the ESB response Message instance
The HttpResponse object can contain the following properties, which are mapped onto the outgoing HTTP gateway response:

Table 10.14. 

Property Description
The HTTP Response/Status Code (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)to be set on the gateway response.
The response payload MIME Type.
The response payload content encoding.
The response payload content length.
A java.util.List<HttpHeader> containing the request headers.


Using the HttpResponse class is efficient because this class is also used by internal actions such as the HttpRouter, making it easy to perform proxying operations using this gateway.


The response payload content encoding can also be set through the HttpResponse instance as is the HTTP response status code (ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" />).
By default, this gateway will wait for 30,000 ms (30 s) for the synchronous service invocation to complete, before raising a ResponseTimeoutException.  To override the default timeout, configure the "synchronousTimeout" property:
    <http-gateway name="Http" urlPattern="esb-cars/*">
        <property name="synchronousTimeout" value="120000"/>
You can map action pipeline exceptions to specific HTTP response codes through the ESB configuration. The mappings can be specified in the top level <http-provider> and can also be specified directly on the <http-gateway>, allowing per-listener override of the exception mappings defined "globally" on the <http-provider>.  Here is an example of an exception mapping made directly on a <http-gateway> configuration:
<http-gateway name="http-gateway">
        <mapping class="com.acme.AcmeException" status="503" />
Configuring exception mappings at the <http-provider> level is exactly the same.
You can also configure a mapping file, which is a simple .properties format file containing "{exception-class}={http-status-code}" mappings.  The file is looked up on the class path and should be bundled inside your .ESB deployment.  It is configured as follows (this time on the <http-provider>):
<http-provider name="http">

    <!-- Global exception mappings file... -->
    <exception mappingsFile="/http-exception-mappings.properties" />