Transport HTTP Documentation
Overview
The transport HTTP bundle provides both an HTTP channel for other bundles to use
and also an inbound HTTP dispatcher for various application containers to use.
Using the dispatcher
The HTTP dispatcher encapsulates configuration and handling of inbound HTTP chains
listening for traffic. Once a request arrives, it will fire an event that any available
HTTP containers can check against their applications and either claim or ignore. It
provides request/response handling in the com.ibm.websphere.http package, which is
similar but simpler than a servlet spec of the HTTP traffic.
Steps to use:
- The container must implement com.ibm.websphere.http.HttpContainer and provide that
as a DS component.
- If the container wants to delay starting the listening chains until an application
is discovered, then it should have a DS dependency on the com.ibm.websphere.http.HttpDispatcherService
and keep that as a ServiceReference. Once the application is found, performing a bundle
context getService() on that ServiceReference will then start the HTTP dispatcher
and the chains, if not already started. If there is no DS dependency from the container to
the dispatcher, then the HTTP dispatcher and the chains will start as soon as this
container component starts.
- The container must listen for an event with the topic of com/ibm/websphere/http/request/ARRIVED.
The connection can be pulled from the event property map by using the HttpInboundConnection.KEY
string, and the individual request and response objects are pulled from the connection. Message
bodies are handling with InputStream and OutputStreams on the message.getBody() call.
- If the container is claiming this request, it must add a property to that event
map. The key is HTTPRequestClaimed and a value of Boolean.TRUE. This will prevent the
event from being handed to other containers for review, as each container receives this
event serially.
- The container can fill in appropriate information on the response object and write
data through the OutputStream class. Once complete, the container must call the
HttpInboundConnection.finish() api to signal completion. If it fails to do so, then
the connection is orphaned and will eventually time out when the client quits
waiting for further communication.
- There is no configuration information in the container related to the dispatcher. The
container will receive HTTP traffic from any listening chain configured in the HTTP
bundle and would need to use vhost mapping in the container itself if particular applications
only support certain hostnames or ports.
Using the channel
Other bundles can use the HTTP inbound or outbound channels in their own chains,
simply by including the channel type of "HTTPInboundChannel" or "HTTPOutboundChannel"
in their channel/chain configurations. They would then program against the HTTP channel
and GenericBNF public APIs (com.ibm.wsspi.http.channel and com.ibm.wsspi.genericbnf).
Using the EncodingUtils
The EncodingUtils DS component provides string locale and converter methods. It has
locale mappings that used to ship in WAS property files. It also has internal pooling
of locale and supported encodings for faster use.
Using the HttpDateFormat
The HTTP date format service provides apis for creating and formatting, or parsing,
various HTTP date formats. This contains all the necessary logic for handling the
multiple possible HTTP date formats, from plain ASCII to various RFC definitions. It
internally uses threadlocal SimpleDateFormat objects to reduce the overhead as much
as possible for users of the service.
RequestContext queries
HTTP dispatcher provides various HTTP information through the request context.
Using the GlobalContext service, the /request/http queries are routed to the
HTTP dispatcher's current request on that Event thread. Valid queries include:
- /request/http/uri, read-only, String, request URI
- /request/http/method, read-only, String, request method (GET/POST)
- /request/http/scheme, read-only, String, request scheme (http, https)
- /request/http/query, read-only, String, request query string
- /request/http/version, read-only, String, protocol version
- /request/http/input, read-only, InputStream, request body
- /request/http/remote/address, read-only, String, client hostname
- /request/http/remote/port, read-only, String, client IP
- /request/http/local/address, read-only, String, local hostname
- /request/http/local/port, read-only, String, local port
- /request/http/headers/in/name, read-only, String, request header of that name
- /request/http/sent, read-only, String, whether response has been sent
- /request/http/status, read-write, String, response status code
- /request/http/headers/out/name, read-write, String, response header of that name
Bundle configuration
- EncodingUtils configuration includes mappings of locales and encodings in the
com.ibm.ws.transport.http.encoding/bundle.cfg file.
- The com.ibm.ws.transport.http/bundle.cfg contains configuration information for
the listening chains as well as the NCSA access logging component. The listening ports
are definitions including TCP endpoints, channels, and chains.