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.
- SOAPInput with SOAPReply
- HTTPInput with HTTPReply
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 IBM® 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, IBM 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
- Integration node listeners
- Using both integration node and embedded listeners
- Configuring listeners
Integration server (embedded) listenersEach 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).
mqsireportproperties integrationNodeName -e default -o ExecutionGroup -n soapNodesUseEmbeddedListener
connector has its own assigned port, which is allocated from a range of numbers, as required. The
default range for the HTTPConnector is
7842; the default
range for the HTTPSConnector is
7884. The first integration
server to start an embedded listener is allocated port
7800, the second is
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 listenersThe 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
mqsichangeproperties integrationNodeName -b httplistener -o HTTPListener -n startListener -v false
has its own assigned port; default values are
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.
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.