About Listeners

Learn how to add and modify listeners for an API Gateway or API Gateway Cluster.

Table of Contents

  1. Overview
  2. Supported Listener Types
  3. Adding a Listener
  4. Listener configuration: HTTP
  5. Listener configuration: HTTPS
  6. Listener configuration: JMS
  7. Listener configuration: AMQP
  8. Listener configuration: AMQPS

Overview

In general, a listener is an object that executes some code when triggered by an event. A listener monitors events happening in the program and acts based on how it's programmed to act in certain events.

In the context of the API platform, a listener is the server process that listens for and accepts incoming connection requests from client applications. Listeners are added to an API Gateway or an API Gateway cluster; they are then mapped based on matching listener names.

Supported Listener Types

Policy Manager supports the following listener types:

  • HTTP
  • HTTPS
  • JMS
  • AMQP
  • AMQPS

Back to top

Adding a Listener

Follow the procedure below to add a listener. Refer to the applicable section for details about how to configure a specific listener type, or use the help to the left of the page.

To add a listener
  1. Log in to Policy Manager.
  2. Navigate to the Containers folder: Workbench > Browse > Organization > Containers. The Containers summary page is displayed, as shown below.

    Container summary page

  3. Click to select the container you want to add a listener for. The Container Overview page is displayed, with a summary of information about the current container. The Inbound Listeners Portlet displays the current listener configuration, as shown below.

    Container Overview page

  4. Click Add Container Listener. The Select Container Listener Type page is displayed.
  5. Choose a listener type from the drop-down list and click Next. The Configure page for the specified listener type is displayed.
  6. In the top section, configure the general listener properties (these are the same for all listener types):
    • Listener Name—A unique instance name for the listener.
    • Description—A short description for the listener.
  7. In the second section, configure the listener properties based on your specific requirements. This sectiion is different for each listener type. For information about specific configuration fields, refer to the applicable section:
  8. HTTP, HTTPS, and JMS only: Configure thread pool values. The thread pool is used to manage the thread configuration for the estimated volume of transactions that will be processed through your production site. Each request requires one thread. If the thread pool configuration is configured with a maximum thread pool size of 256, the container will support 256 concurrent requests. If more concurrent requests are required in a container, the thread pool configuration for the specific listener can be updated within the container. The initial display shows default values. Choices:
    • Minimum—The minimum number of threads that are reserved for requests from applications. Default: 5.
    • Maximum—The maximum number of threads that are reserved for requests from applications. Default: 500.
    • Idle Thread Timeout (mls)—The number of milliseconds after which idle threads are removed from the thread pool. Default: 180,000 (3 minutes).

    Note: The thread pool is dynamically adjusted between the minimum and maximum values. The minimum thread pool setting signals the server to allocate at least that many threads in reserve for application requests. That number is increased up to the maximum specified thread pool size.

  9. HTTP and HTTPS only: In the Service Hosting section, if you want to clone services hosted on other listeners to match the services hosted on the current listener, select the Clone services hosted on other listener(s) checkbox, and then select a listener type out of available options. Possible choices: All Listeners, the default HTTP listener, or selected listeners that you have defined.

    Note: Once you've saved the listener configuration, you cannot change the Service Hosting setting.

  10. Click Finish.

Back to top

Listener configuration: HTTP

Many of the listener configuration fields, such as name/description and thread pool fields, are the same for multiple listener types. These are briefly defined in the procedure above (see Adding a listener step 8).

HTTP listener

The center section of each listener page includes values specific to the individual listener. For HTTP listeners, those fields are defined below. You can also use the help to the left of the page.

Bind to all interfaces
Based on your network infrastructure and security requirements, you can configure a container listener to listen to all network interfaces through one port, or you can limit the container listener to one port.
Checked: The container listener is configured to listen to all network interfaces through one port.
Cleared: The container listener listens through one port only.
Host Name
The Host Name portion of the Listener URL.
Port Number
The Port Number portion of the Listener URL.
Context Path
The Context Path portion of the Listener URL. Entering a Context Path is optional. This field only displays for Network Director containers and legacy containers.
Note: The Context Path only applies to services hosted in the container. It does not refer to or change the path of the Akana Policy Manager Console or the Akana Administration Console associated with a container.
The Host Name, Port Number, and Context Path combined represent the full URL. The URL represents the name or address of the machine on which the container is running. Be sure to use a name or IP address that will be recognizable to all computers that will be accessing this container. For example, if computers outside your network will be using the container, use a fully-qualified domain name or an IP address that is visible and accessible outside the network.

Back to top

Listener configuration: HTTPS

Many of the listener configuration fields, such as name/description and thread pool fields, are the same for multiple listener types. These are briefly defined in the procedure above (see Adding a listener).

HTTPS listener

The center section of each listener page includes values specific to the individual listener. For HTTPS listeners, those fields are defined below. The fields are essentially the same as for an HTTP listener, with the addition of the Client Certificates field.

You can also use the help to the left of the page.

Note: in order to set up a secure listener, you must have existing keys/certificates. See Managing Keys.

Bind to all interfaces
Based on your network infrastructure and security requirements, you can configure a container listener to listen to all network interfaces through one port, or you can limit the container listener to one port.
Checked: The container listener is configured to listen to all network interfaces through one port.
Cleared: The container listener is limited to listen through one port.
Host Name
The Host Name portion of the Listener URL.
Port Number
The Port Number portion of the Listener URL.
Context Path
The Context Path portion of the Listener URL. Entering a Context Path is optional. This field only displays for Network Director containers and legacy containers.
Note: The Context Path only applies to services hosted in the container. It does not refer to or change the path of the Akana Policy Manager Console or the Akana Administration Console associated with a container.
The Host Name, Port Number, and Context Path combined represent the full URL. The URL represents the name or address of the machine on which the container is running. Be sure to use a name or IP address that will be recognizable to all computers that will be accessing this container. For example, if computers outside your network will be using the container, use a fully-qualified domain name or an IP address that is visible and accessible outside the network.
Client Certificates
Defines behavior with regard to client certificates. Choices:
  • ignore
  • accept
  • require
If you choose accept or require, you'll see additional fields for inbound and outbound certificates, where you can select and upload a certificate to include in your container configuration.

Back to top

Listener configuration: JMS

Many of the listener configuration fields, such as name/description and thread pool fields, are the same for multiple listener types. These are briefly defined in the procedure above (see Adding a listener).

JMS listener

The center section of each listener page includes values specific to the individual listener. For JMS listeners, those fields are defined below. You can also use the help to the left of the page.

JNDI URL
Enter the URL where the Java Naming and Directory Interface (JNDI) server can be accessed.
JNDI Initial Context
Enter the starting point for resolution of names for naming and directory operations.
JMS Destination Factory Name
Enter a topic name or queue with a physical resource for the Java Message Service (JMS) Destination Factory.
Connection Properties
Optional, user-defined additional properties that allow you to specify the messaging engine that an application will connect to. Only message properties of type String are supported. To configure a connection property, define a Name and Value. You can also remove an existing property and/or add a new one.

Back to top

Listener configuration: AMQP

Many of the listener configuration fields, such as name/description, are the same for all listener types. These are briefly defined in the procedure above (see Adding a listener).

AMQP listener

The center section of each listener page includes values specific to the individual listener. For AMQP listeners, those fields are defined below. You can also use the help to the left of the page.

AMQP Version
Supported versions include 1.0, 0.9.1, and 0.9.
Virtual Host Name
The virtual host name of the AMQP broker.
Host
The host name. You can also remove an existing host and/or add a host.
Port
Displays the default port, 5672, used for AMQP connections.
Authentication Required
If the AMQP binding will be used to authenticate an AMQP registry where AMQP destinations or targets are located, or to authenticate the AMQP system itself, authentication might be required. To enable authentication, select the checkbox and specify the Identity Source, Username, and Password.
Connection Properties
Optional, user-defined additional properties that allow you to specify the messaging engine that an application will connect to. Only message properties of type String are supported. Connection Properties are configured by entering a "Property Name" and "Property Value. You can enter unlimited connection properties.

Back to top

Listener configuration: AMQPS

Many of the listener configuration fields, such as name/description, are the same for all listener types. These are briefly defined in the procedure above (see Adding a listener).

AMQPS listener

The center section of each listener page includes values specific to the individual listener. For AMQPS listeners, those fields are defined below. The fields are essentially the same as for an AMQP listener, but the default port name is different.

You can also use the help to the left of the page.

Note: in order to set up a secure listener, you must have existing keys/certificates. See Managing Keys.

AMQP Version
Supported versions include 1.0, 0.9.1, and 0.9.
Virtual Host
The virtual host name of the AMQP broker.
Host
The host name. You can also remove an existing host and/or add a host.
Port
Displays the default port, 5671, used for AMQPS connections.
Authentication Required
If the AMQP binding will be used to authenticate an AMQP registry where AMQP destinations or targets are located, or to authenticate the AMQP system itself, authentication might be required. To enable authentication, select the checkbox and specify the Identity Source, Username, and Password.
Connection Properties
Optional, user-defined additional properties that allow you to specify the messaging engine that an application will connect to. Only message properties of type String are supported. To configure a connection property, define a Name and Value. You can also remove an existing property and/or add a new one.

Back to top