Event processing
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.
Protocol listeners
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.
Pingability
The listeners can be configured to respond to ping requests
with user-specified response codes. Usually, ping requests come
before complete requests and are used to validate that the listener
URL is alive. The Pingability hierarchical property is used to capture the configuration
parameters. If this service is enabled in the listener, the listener
checks to confirm that the method of the request equals the method
defined in any of the child properties of Pingability and responds with a user defined status-code and reason.
Note:
Defining any HTTP method as pingable will stop the
listener from generating requests containing that method. Therefore,
POST or GET methods should not be set as Pingable, unless no real
request will arrive using those HTTP methods.
HTTP and HTTPS protocol
listener processing
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 sends a request
message to the HTTP or HTTPS listener. The client should use the
HTTP POST or GET 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 26 summarizes the order
of precedence of rules used by the listener to determine the Charset,
MimeType, ContentType and Content-Type header for inbound
messages when the payload is present.
Note:
For inbound messages when the
payload is not present,
refer to
Table 27, which summarizes
the order of precedence of rules used by the listener to determine
the Charset, MimeType, ContentType and
Content-Type header.
Table 26. Processing rules for inbound message when payload is present
Order of Precedence |
Charset |
MimeType |
ContentType |
Content-Type header |
1 |
Incoming HTTP message Content-Type header |
URLsConfiguration property value for this listener |
Incoming HTTP message Content-Type header |
Incoming HTTP message Content-Type header |
2 |
URLsConfiguration property value for this listener |
Default to ContentType |
|
|
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. |
|
|
|
Table 27. Processing rules for inbound message when payload is not present
Order of Precedence |
Charset |
MimeType |
ContentType |
Content-Type header |
1 |
Read from EmptyRequestRule listener property |
Read from EmptyRequestRule listener property Listener |
Invoked data handler may return ContentType as
part of Content-Type header |
Invoked data handler may return Content-Type
header |
2 |
Charset will not be used. |
Fail the request |
|
|
3 |
|
|
|
|
As shown Table 26:
- 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 request 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 28 summarizes the order
of precedence for rules used by the listener when determining the
Charset, MimeType, ContentType, and Content-Type header
for response messages when the payload is present.
Note:
For response messages when the
payload is not present,
refer to
Table 29, which summarizes
the order of precedence for rules used by the listener when determining
the Charset, MimeType, ContentType, and
Content-Type header.
Table 28. Processing rules for outbound synchronous response message when payload is present
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. |
Default to ContentType |
|
|
4 |
If the ContentType is text/*, default to ISO-8859-1. Otherwise, charset will not be used. |
|
|
|
Table 29. Processing rules for outbound synchronous response message when request payload is not present
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. |
Default to ContentType |
|
|
4 |
If the ContentType is text/*, default to ISO-8859-1. Otherwise, charset will not be used. |
Fail the response |
|
|
As shown in Table 28,
- 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.
Unsupported HTTP protocol
listener processing features
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 listener processing using secure
sockets
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 and delivery
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
Event sequencing
The connector may deliver events in any sequence.
Event triggering
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
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
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
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
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
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.
