Text over HTTP service binding

To publish an information service that flexibly accepts messages through HTTP, attach the Text over HTTP binding to the information service.

Overview of this binding

HTTP request and response payloads are passed "as is" to the underlying InfoSphere® Information Services Director providers. To remain flexible, the Text over HTTP implementation makes no assumptions about the format of the HTTP request or response payload, so you can customize HTTP requests and payloads to use SOAP, XML, text, and so on.

Note: The underlying IBM® InfoSphere Information Services Director provider (such as the IBM InfoSphere DataStage® job) is responsible for understanding and composing this format.

The Text over HTTP binding supports many features:

Ability to transform the request payload through XSLT style sheets that you provide, before it is sent to the information service providers and to transform the information service provider results by using XSLT before the results are returned in the HTTP response. XSLT 1.0 is the supported version.
You can map transport data units (HTTP headers, HTTP request parameters, HTTP payload) of the HTTP protocol to and from InfoSphere Information Services Director service input and output arguments
Multi-part HTTP request support.
You can receive and send complex SOAP messages with arbitrarily complex XML types. This ability can be required if the InfoSphere Information Services Director service must implement a predefined web service interface, for example, to implement a given WSDL.

The Text over HTTP binding pane includes options for the following features:

Description of the binding.
Service Description File path. Specify a description document, which can be used to provide documentation for service users. The documentation that you provide can explain how service users can call the service. This document can be in any format, such as HTML, XML, text, PDF (Portable Document Format) or .zip file. This document is packaged as part of the service and is accessible by a browser using a URL of the form http://server:port/wisd-txhttp/appname/servicename. If you specify a WSDL document as the service description file, make sure to select the WSDL Service Description check box.
WSDL Service Description. If you are providing a WSDL document as the service description document, select this option to flag the service description document as a WSDL document. The service user can access the WSDL document by using the URL previously mentioned.
Important: You must make sure that the InfoSphere Information Services Director service can properly handle the SOAP requests that will be generated from the provided WSDL.
Include this binding check box. To exclude the binding from the deployment of the application that contains this information service, clear this setting.
Security options
- Requires Authentication check box. If you select this option, the authentication mechanism uses HTTP Basic Authentication only. In particular, if the you use SOAP for the HTTP payload format, the SOAP specific authentication protocol (like WS-Security) is not supported because the protocol will require a true SOAP service to be generated in the application server.
  To force the authentication, all service operations require the InfoSphere Information Services Director Consumer role to be invoked. This role is declared at the service implementation level (all bean operations in the ejb-jar.xml of the session bean) and at the Text over HTTP servlet level (all URLs in the web.xml of the generated servlet). The URL to access the service description document is also protected by the InfoSphere Information Services Director Consumer role.
- Requires Confidentiality check box. If you select this option, a note will display that HTTPS/SSL is required to call this service. Only HTTPS is supported for confidentiality support. Specifically, if the you use SOAP for the HTTP payload format, SOAP specific confidentiality protocol (WS-Security/XML encryption) is not directly supported by the Text over HTTP binding. You can still decide to pass WS-Security encrypted data directly down to the information provider if the information provider has the ability to decode it. However, the Text over HTTP binding does not support any automatic encryption or decryption of this data.

Input mapping

Input Mapping. You map HTTP protocol data units to service-input arguments. This process is HTTP request mapping.

InfoSphere Information Services Director supports only the following service operation input arguments:

One or more scalar input arguments, for example, int, string, or boolean.
A single complex type input argument that contains only scalar attributes.
A single array of a complex type that contains only scalar attributes.

Define the mapping between the service input arguments and the HTTP protocol data units (HTTP headers, HTTP request parameters, or HTTP payload) in the following ways:

Individual scalar input arguments can be mapped to any of the HTTP protocol data units.
Individual scalar attributes of a complex type input argument can be mapped to any of the HTTP protocol data units.
Individual scalar attributes of an array of complex type input arguments can be mapped to any of the HTTP protocol data units. In this case, an array with a single element is created for a given HTTP request and passed as the service input argument

Type. In the Text over HTTP mapping process, the HTTP request is mapped to service input arguments. The following HTTP protocol data units can be used for an HTTP request. For each scalar operation input argument, you must first select the type of HTTP protocol data unit (header, body, query parameters, and so on) that the value of the argument comes from. Then you can specify the HTTP data units that you want to use for the selected type:

Fixed

You can provide a fixed value for any scalar operation service input argument. Regardless of the content of the incoming HTTP request, this specific input argument always has the entered value when the InfoSphere Information Services Director service is called.

HTTP Payload

If HTTP Payload is selected, the complete payload (the HTTP body) is passed as the service input argument.

Optionally provide an XSLT stylesheet to transform a valid XML payload before it is passed down to the mapped scalar operation input argument.

HTTP Header

Select a standard HTTP header or type a custom HTTP header name.

Some HTTP headers are available only for requests and responses. You must select the appropriate HTTP headers according to the HTTP protocol specification.

HTTP Part

Individual parts of the HTTP payload in a multipart/form-data request. Specify the name of the part that needs to match the name attribute of the Content-Disposition header of the part.

Optionally provide an XSLT stylesheet to transform a valid XML payload part before it is passed down to the mapped scalar operation input argument.

HTTP Parameter

Specify the name of a HTTP URL parameter. The HTTP parameter is encoded as part of the URL and is only supported for the HTTP GET method. (The POST method requires use of HTTP Payload.)

CGI Variable and/or Servlet Variable

Select a standard CGI variable and/or servlet variable. See Table 1 for a list of CGI variables and/or servlet variable properties that you can access as part of the HTTP request mapping.

Table 1. CGI variable and/or servlet variable properties
HTTP Component	Mapping	HttpServletRequest
SERVER_NAME	The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.	getServerName()
SERVER_PROTOCOL	The name and revision of the information protocol this request came in with. Format: protocol/revision.	getProtocol()
SERVER_PORT	The port number to which the request was sent.	getServerPort()
Scheme	Returns the name of the scheme used to make this request, for example, HTTP or HTTPS.	getScheme()
REQUEST_METHOD	The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", and so on.	getMethod()
PATH_INFO	The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. This information should be decoded by the server if it comes from a URL before it is passed to the CGI script.	getPathInfo()
PATH_TRANSLATED	The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.	getPathTranslated()
Servlet Path	Returns the part of this request's URL that calls the servlet. This is the same as the SCRIPT_NAME CGI variable.	getServletPath()
QUERY_STRING	The query information is the information that follows the question mark (?) in the URL that referenced this script. The query information should not be decoded. This variable should always be set when there is query information, regardless of command line decoding.	getQueryString()
REMOTE_HOST	The host name making the request. If the server does not have this information, it should set REMOTE_ADDR and leave this unset.	getRemoteHost()
REMOTE_ADDR	The IP address of the remote host making the request.	getRemoteAddr()
AUTH_TYPE	If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.	getAuthType()
REMOTE_USER	If the server supports user authentication, and the script is protected, they have authenticated as this user name.	getRemoteUser()
Request URI	Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request.	getRequestURI()
Request URL	Reconstructs the URL that the client used to make the request.	getRequestURL()
Context Path	Returns the portion of the request URI that indicates the context of the request (this is a servlet property and not a CGI variable).	getContextPath()

The same HTTP request data units can also be mapped to different service input arguments. For example, the HTTP payload can be mapped to one or more different InfoSphere Information Services Director service input arguments, with a different XSLT stylesheet for each. This capability gives you the option to extract different parts of the HTTP payload using XSLT to provide specific values for different service input arguments.

Output mapping

Output Mapping. You map service output arguments to the HTTP response. This process is HTTP response mapping.

InfoSphere Information Services Director supports only the following service operation output arguments:

A single scalar output return argument, such as an int, string, or boolean return.
A single complex type output argument that contains only scalar attributes.
A single array of a complex type that contains only scalar attributes.

Use the mapping process to define the mapping between the service output argument and the HTTP response protocol data unit:

Individual scalar output arguments, including complex types, can be mapped to any of the HTTP protocol data units.
In a complex type output argument, individual scalar attributes of this complex type can be mapped to any of the HTTP protocol data units.
In an “array of complex type” output argument, individual scalar attributes of this complex type can be mapped to any of the HTTP response protocol data units. Only the first element in the array is used to generate the HTTP response; any other elements in the array are ignored.
Type. In the Text over HTTP mapping process, output arguments are mapped to HTTP response data units. The HTTP protocol data units supported for an HTTP response are as follows:
HTTP Header

Select a standard HTTP header or type a custom HTTP header name. Your options include the Content-Type header, which enables you to specify the media type of the HTTP response. If the Content-Type header is not mapped to any values, the application or octet-stream is used by default.

HTTP Payload

If selected, the value of the selected service output argument is taken "as is" and is used to set the content of the HTTP response payload (also called the HTTP response body).

Optionally provide an XSLT style sheet to transform the service output argument before it is used to set the content of the HTTP response payload/body. The selected service output argument must be a valid XML document because XSLT will only understand an XML document as input.

Note: The same service output argument can also be mapped to different HTTP response data units. For example, the same scalar value of the service output argument can be used to set the value of an HTTP response header as well as of the HTTP response payload.
XSLT. For any scalar value of the service output argument of type string, you can provide an XSLT stylesheet to transform the string before it is used to set the value of the mapped HTTP response data units. In this case, ensure that the underlying service provider returns the string as a valid XML document so that it can be properly handled by the XSLT style sheet.
The combination of (1) mapping the same service output argument to different HTTP response data units and (2) using the XSLT support for string output values allows you to define a service operation that (a) can return a single string that can be a complex XML document and (b) extract different pieces of this XML document to assign values to the different HTTP response data units.
You can provide the value of the HTTP content-type header that specifies the media-type of the HTTP payload. The HTTP payload and media-type must match. It is your responsibility to make sure that the payload and media-type match. Verify that the underlying information provider returns the data in the proper format, or use an XSLT stylesheet to transform the XML provider data to match the specified format.

Calling InfoSphere Information Services Director services by using the Text over HTTP binding

The URL syntax

A unique base URL is used to identify which service an HTTP request is directed to. This base URL is defined as follows:
http://servername:port/wisd-txhttp/<application-name>/<service-name>
The path elements enclosed in < and > are replaced by the actual InfoSphere Information Services Director application name and service name.
Some software and hardware might not allow certain characters in the URL.
The name of the actual operation to call can be provided using either of these two options:
- Adding the name of the operation at the end of the base URL:
  http://servername:port/wisd-txhttp/<application-name>/<service-name>/<operation-name>
- Using the SOAPAction HTTP header to specify the name of the operation (in case the end-user decides to use text over HTTP with SOAP messages)
Both options are supported at all times. If both options are specified simultaneously, the first option (adding the operation name to the end of the base URL) takes precedence.

Error handling

A service calling error results in an HTTP error that is sent back to the client by the following rules:

HTTP 500 error (Internal Server Error): Any unexpected errors that occur during the service invocation results in an HTTP 500 error (Internal Server Error) with the stack trace of the error provided as the response HTTP payload. This includes any XSLT stylesheet processing errors.; There is no automated support for SOAP fault generation in the event that SOAP/HTTP is used as the HTTP payload format with this binding. Using XSLT, you can examine the data that is returned by the underlying provider and possibly generate an HTTP response containing a SOAP fault. In the event of a Java™ exception during the processing of a request, no SOAP fault will be generated; only an HTTP error will be sent back to the caller.
HTTP 404 error (Not Found): An attempt to access an operation that does not exist will result in an HTTP 404 error (Not Found).
HTTP 400 error (Bad Request): Sending invalid data will result in an HTTP 400 error (Bad Request). For example, if the wrong service input arguments are used and can not be properly decoded, such as sending a string while an integer is expected, the client receives this error.; Unsupported combinations of HTTP methods and content type will also result in an HTTP 400 error.
HTTP 405 error (Method Not Allowed): Using an HTTP GET operation when only a POST is allowed will result in an HTTP 405 error (Method Not Allowed).