HTTP listeners

You can choose between integration node listeners and integration server (embedded) listeners to manage HTTP messages in your HTTP or SOAP flows. Learn about the two types of listener, how ports are assigned to them, and how you can switch from one to the other for individual integration servers.

Your choice of listener affects message flows that handle inbound web service requests and synchronous replies by using the following nodes:
  • SOAPInput with SOAPReply
  • HTTPInput with HTTPReply
Message flows that do not handle inbound requests but that instigate outbound requests or asynchronous responses by using the following nodes are not affected:
  • SOAPRequest
  • SOAPAsyncRequest
  • SOAPAsyncResponse
  • HTTPRequest
  • HTTPAsyncRequest
  • HTTPAsyncResponse

The choice of listener also affects integration services and REST APIs. Integration services use a SOAPInput node, so they use the listener specified for SOAP nodes. REST APIs use an HTTPInput node, so they use the listener specified for HTTP nodes.

The integration node listener requires access to system queues on the queue manager specified on the integration node, so you must install WebSphere® MQ Server if you want to use an integration node listener. However, if you use HTTP nodes or SOAP nodes with the integration server embedded listener, WebSphere MQ is not required.

For more information about how your choice of listener relates to your HTTP topology, see HTTP topology configuration.

Integration server (embedded) listeners

Each integration server has an embedded listener. The listener is associated with an HTTPConnector object and an HTTPSConnector object. The HTTPConnector object controls the runtime properties that affect the handling of HTTP messages. For example, run the following command to change the port on which the embedded listener for integration server default on integration node integrationNodeName listens for HTTP messages: 
mqsichangeproperties integrationNodeName -e default -o HTTPConnector 
  -n explicitlySetPortNumber -v 8085

The HTTPSConnector object controls the runtime properties that affect the handling of HTTPS (HTTP Secure) messages. Run the following command to display these properties for integration server default on integration node integrationNodeName:

mqsireportproperties integrationNodeName -e default -o HTTPSConnector -r

For further details, including more examples, see Integration server HTTP listener parameters (SOAP and HTTP nodes).

By default, SOAPInput, SOAPReply, and SOAPAsyncResponse nodes use the integration server listener. If integration server default on integration node integrationNodeName is using the integration node listener, the following command returns a value of false:
mqsireportproperties integrationNodeName -e default -o ExecutionGroup -n soapNodesUseEmbeddedListener

Each connector has its own assigned port, which is allocated from a range of numbers, as required. The default range for the HTTPConnector is 7800 - 7842; the default range for the HTTPSConnector is 7843 - 7884. The first integration server to start an embedded listener is allocated port 7800, the second is allocated 7801, and so on.

If you deploy a message flow to multiple integration servers, the port number is incremented by one for each successive deployment. Assume that no embedded listeners have as yet been started for these integration servers. In this case, the message flow that is deployed to the first integration server receives requests on port 7800. The next message flow uses port 7801, and so on, up to the specified limit of 7842. In this scenario, you typically use an intermediary router that listens on one port, then distributes the requests across the range of ports that you are using.

You can change these port number ranges, and you can allocate a specific port to an integration server, by using the mqsichangeproperties command.

If you restart an integration server, the embedded listeners continue to use the same ports as before the restart.

Integration node listeners

The integration node listener is associated with an HTTPConnector object for properties related to handling HTTP messages, and an HTTPSConnector object for properties related to handling HTTPS messages. For example, run the following command to change the port on which the integration node listener for integrationNodeName listens for HTTP messages: 
mqsichangeproperties integrationNodeName -b httplistener -o HTTPConnector 
  -n port -v 8085
Integration node listener properties that apply to HTTP and HTTPS messages are controlled by the HTTPListener object. For example, to disable the integration node listener for integrationNodeName, run the following command: 
mqsichangeproperties integrationNodeName -b httplistener -o HTTPListener 
  -n startListener -v false

Each connector has its own assigned port; default values are 7080 for HTTP and 7083 for HTTPS. You can change these port numbers by using the mqsichangeproperties command.

By default, HTTPInput and HTTPReply nodes use the integration node listener.

You can configure one or more integration servers so that HTTP nodes that you deploy to those integration servers use the embedded listener, or so that SOAP nodes that you deploy to those integration servers use the integration node listener.

Using both integration node and embedded listeners

Because the option to use the embedded listener is at the integration server level, you can change your configuration such that some integration servers use the integration node listener for HTTP nodes, SOAP nodes, or both, and other integration servers use the embedded listener for HTTP nodes, SOAP nodes, or both.

However, if you disable the integration node listener, the integration server listeners are used for all HTTP and SOAP nodes, even if you have not explicitly enabled support for them. Therefore, if you set all relevant integration node and integration server properties to false, the integration server listeners handle all HTTP messages.

The HTTPRequest node communicates directly with the HTTP transport, and is therefore unaffected by your choice.

If you change the listener and port that are processing your HTTP or HTTPS messages, you must ensure that you also update your applications to use the updated configuration.

Configuring listeners

When you have decided on the configuration that you want:

  • If you want to use the integration node listener for HTTP nodes in all integration servers, and the embedded listener for SOAP nodes in all integration servers, you do not have to change your configuration.
  • If you are currently using the integration node listener for one or more integration servers, and want to switch to using embedded listeners, follow the instructions in Switching from an integration node listener to embedded listeners.
  • If you are currently using the integration server listener for one or more integration servers, and want to switch to using the integration node-wide listener, follow the instructions in Switching from embedded listeners to an integration node listener.