During event processing, the connector uses protocol listeners
and the configured data handler(s) to convert request messages from
HTTP service clients to business objects that can be manipulated by
collaborations. Protocol listeners play a crucial role in event
processing.
HTTP requests may come over HTTP or HTTPS transports. The
listener monitors the arrival of such requests on its transport
channel. There are two protocol listeners and corresponding
channels:
- HTTP protocol listener
- HTTPS protocol listener
Each of these consists of a thread that listens on its
transport. When it receives a request message from a client, the
listener registers the event with the protocol listener
framework.
The protocol listener framework manages the protocol listeners,
scheduling requests as resources are available. You configure the
listeners and aspects of the protocol listener framework when you
set values to connector-specific properties. Among the protocol
listener framework properties you can configure are the
following:
- WorkerThreadCount Total number of threads available to
the protocol listener framework, which is the number of requests
that it can process in parallel.
- RequestPoolSize Maximum number of requests that can be
registered with the protocol listener framework. If it receives
more than this maximum requests, it will no longer register new
requests.
These two connector-specific properties control memory
allocation in a way that prevents protocol listeners from clogging
the connector with infinite events. The allocation algorithm is as
follows: At any time, the connector can receive a total number of
events equal to WorkerThreadCount + RequestPoolSize. It can process
WorkerThreadCount number of requests in parallel.
You can plug additional protocol listeners into the protocol
listener framework. For further information, see Creating multiple protocol
listeners andConnector-specific configuration
properties.
The HTTP(S) protocol listener consists of a thread that
continuously listens for HTTP(S) requests from clients. The
listener thread binds the host and port that are specified in the
Host and Port connector-specific configuration (listener)
properties. Another configuration
property--RequestWaitTimeout--defines the interval during which the
listener waits for a request before checking whether the connector
has shut down.
Figure 14 illustrates HTTP
protocol listener processing for a synchronous operation.
Figure 14.
HTTP protocol listener: synchronous event processing

Figure 15 shows HTTP protocol
listener processing for an asynchronous operation.
Figure 15.
HTTP protocol listener: asynchronous event processing

When a client initiates a HTTP or HTTPS request, it posts a
request message to the HTTP or HTTPS listener. The client should
use the HTTP POST method to invoke the protocol listener URL.
When an HTTP(S) request arrives, the listener registers the
request with the protocol listener framework, which schedules the
event for processing as resources become available. The listener
then extracts the protocol headers and the payload from the
request.
Table 25 summarizes the order
of precedence of rules used by the listener to determine the
Charset, MmeType, ContentType and Content-Type header for inbound
messages.
Table 25.
HTTP(s) protocol listener processing rules for inbound
message
Order of
Precedence |
Charset |
MimeType |
ContentType |
Content-Type
header |
1 |
Charset parameter value
from the incoming HTTP message Content-Type header value |
URLsConfiguration
connector property value for this listener |
Incoming HTTP message
type/subtype value from the Content-Type header value |
Incoming HTTP message
Content-Type header |
2 |
URLsConfiguration
property value for this listener |
|
|
|
3 |
If the type of the
request message ContentType is text with any subtype (for
example, text/xml, text/plain, etc.), default to
ISO-8859-1. Otherwise, charset will not be used. |
Default to
ContentType |
|
|
As shown Table 25:
- The protocol listener determines the Charset of the inbound
message according to the following rules:
- The listener attempts to extract the Charset from the charset
parameter of HTTP message Content-Type header value.
- If no Charset value is obtained from the Content-Type header,
then the protocol listener attempts to read the URLsConfiguration
property value for this listener.
- If a Charset value is not obtained using methods described in
the previous steps, and if type of the message ContentType is
text with any subtype (for example, text/xml,
text/plain, etc.), the listener uses a default Charset
value of ISO-8859-1. Otherwise, Charset value is not used.
- The listener determines the MimeType for the response message
according to these rules:
- if you have configured the TransformationRules for the URL used
by the incoming request message, and if the request ContentType
matches the ContentType of a TransformationRule, then the listener
uses the TransformationRule to extract the MimeType for conversion
of the request message into a request business object. The listener
attempts to find the exact TransformationRule match based on the
ContentType value (for example, text/xml) in the
URLsConfiguration property for the requested URL.
- If that fails, the listener attempts to find a
TransformationRule that applies to more than one ContentType under
the request URL (for example */*).
- If all previous steps fail to determine the MimeType, the value
of ContentType will be used as the MimeType to invoke the data
handler and convert the request message into a request business
object.
- The listener determines the ContentType by extracting
type/subtype from the incoming HTTP message Content-Type
header.
- The listener determines the Content-Type header from that of
the incoming HTTP message Content-Type header
If the collaboration is invoked asynchronously, the listener
delivers the request business object to the integration broker and
responds to the client with the HTTP status code 202
Accepted. This concludes listener processing.
If it is a synchronous invocation, the listener invokes the
collaboration synchronously. The collaboration responds with a
response business object.
Table 26 summarizes the order
of precedence for rules used by the listener when determining the
Charset, MimeType, ContentType, and Content-Type header for
response messages.
Table 26.
HTTP(s) protocol listener processing rules for outbound synchronous
response message
Order of
Precedence |
Charset |
MimeType |
ContentType |
Content-Type
header |
1 |
Protocol ConfigMO
Content-Type Header |
MimeType property in the
TLO |
Protocol ConfigMO
Content-Type header |
Protocol ConfigMO
Content-Type header |
2 |
The Charset property
value in the TLO |
The request message
MimeType, but only if the request and response ContentType
match. |
Request message
ContentType |
Construct Content-Type
Header using ContentType and Charset |
3 |
The request message
Charset, but only if the request and response ContentType
match. |
Use ContentType value as
the MimeType |
|
|
4 |
If the ContentType is
text/*, default to ISO-8859-1. Otherwise, charset will not
be used. |
|
|
|
As shown in Table 26,
- The listener determines the Charset for the response message
according to these rules:
- If Charset is specified in the response business object
Protocol Config MO, its value is used.
- If there is no Charset value specified in the response business
object Protocol Config MO header, the listener checks if Charset is
specified in the TLO.
- If there is no Charset specified in the TLO, then if the
response has the same ContentType as the request, the Charset of
the request will be used for the response.
- If the previous steps fail to determine the response Charset
value, and if the type portion of the message ContentType is
text with a subtype of anything (for example,
text/xml, text/plain, etc.), the listener uses a
default Charset value of ISO-8859-1. Otherwise, the Charset value
is not used.
- The listener determines the MimeType for the response message
according to these rules:
- The TLO's MimeType attribute
- If the TLO MimeType attribute is missing, and if the request
and response ContentType match, the listener uses the request
MimeType for the response message.
- Otherwise the listener uses the ContentType value as the
MimeType.
- The listener determines the ContentType for the response
message according to these rules:
- If the Content-Type header is specified in the response
business object Protocol Config MO, the type/subtype portion of the
Content-Type header will used as the ContentType.
- If the Content-Type header is not specified in the response
business object Protocol Config MO, the listener constructs a
Content-Type header using the determined ContentType and Charset
(if the Charset was determined for the response message).
The listener processes the HTTP Protocol Config MO. It is the
responsibility of collaboration to ensure that the header values
passed in the HTTP Protocol Config MO are correct in the context of
the request-response event. The listener populates standard headers
and custom properties according to the following rules:
- The listener will investigate each item of the HTTP Protocol
Config MO in order to ignore special attributes (such as
ObjectEventId).
- Each non-empty header will be put on the outgoing message and
additional processing (for example, the Content-Type header) may
take place.
- Please note that with the above approach, the listener may set
non-standard headers on the message, but will not check that the
message is logically or semantically correct.
- If there are one or more custom properties in the HTTP Protocol
Config MO UserDefinedProperties attribute, the listener will add
them in the Entity Headers Section (the last headers section). For
more on custom properties, see User-defined properties for
event processing.
- Note:
- Specifying any of the following headers in the HTTP Protocol
Config MO is very likely to result in an incorrect HTTP message:
Connection, Trailer, Transfer-Encoding, Content-Encoding,
Content-Length, Content-MD5, Content-Range.
The listener then invokes the data handler to convert the
response business object returned by the collaboration into a
response message.
The listener delivers the response message to the client and
includes a 200 OK HTTP status code. If the collaboration
returns a fault business object, it is converted to a fault
message. This fault message is delivered to the client with a
500 Internal Server Error HTTP code.
The listener then closes the connection and the thread that
processed the event becomes available.
The HTTP protocol listener does not support the following:
- Caching: The protocol listener does not perform any caching
functions as defined in HTTP specifications (RFC2616)
- Proxy: The protocol listener does not perform any proxy
functions as defined in HTTP specifications (RFC2616).
- Persistent Connection: The protocol listener does not support
persistent connections as defined in HTTP specifications (RFC2616).
Instead, the protocol listener assumes that the scope of each HTTP
connection is a single client request. and closes the connection
when the service request is completed. The protocol listener does
not attempt to reuse the connection across the service
invocations.
- Redirections: The protocol listener does not support
redirections.
- Large file transfer: The protocol listener cannot be used for
large file transfers. Alternatively, you may consider passing large
files by reference instead.
- State management: The protocol listener does not support the
HTTP state management mechanism described by RFC2965.
- Cookies: The protocol listener does not support cookies.
HTTPS protocol listener processing is the same as that described
in the HTTP protocol listener processing section except that HTTPS
uses secure sockets. For further information, see SSL.
Event persistence is protocol contingent:
- HTTP protocol listener no persistence and therefore no
guaranteed delivery
- HTTPS protocol listener no persistence and therefore no
guaranteed delivery
The connector may deliver events in any sequence.
The event triggering mechanism depends on how the protocol
listener is configured.
- HTTP protocol listener Listening occurs over a
ServerSocket for HTTP connection requests
- HTTPS protocol listener Listening occurs over a secure
ServerSocket layer for HTTPS connection requests
- Note:
- The connector does not distinguish between Create or Update or
Retrieve or Delete. All such events follow the same approach.
Event detection is performed by each protocol listener. The
event detection mechanism depends utterly on the transport and how
you configure the connector-specific properties for each listener.
For more on these properties, see Connector-specific configuration
properties.
Event status is managed by the protocol listener and depends on
the transport and also on how you configure the listener.
- HTTP protocol listener HTTP is inherently non-persistent
and synchronous in nature. Accordingly, event status is not
maintained.
- HTTPS protocol listener HTTP is inherently
non-persistent and synchronous in nature. Accordingly, event status
is not maintained.
Event retrieval is managed by the protocol listener and depends
on the transport and also on how you configure the listener.
- HTTP protocol listener Events are retrieved by
extracting HTTP requests from the socket.
- HTTPS protocol listener Events are retrieved by
extracting HTTP requests from the socket.
Event archiving is managed by the protocol listener and depends
on the transport and also on how you configure the listener.
- HTTP protocol listener Because of the non-persistent and
synchronous nature of the transport, archiving is not
performed.
- HTTPS protocol listener Because of the non-persistent
and synchronous nature of the transport, archiving is not
performed.
Event recovery is managed by the protocol listener and depends
on the transport and also on how you configure the listener.
- HTTP protocol listener Because of the non-persistent
nature of the transport, event recovery is not performed.
- HTTPS protocol listener Because of the non-persistent
nature of the transport, event recovery is not performed.
