Creating Listeners

Listeners are pieces of JavaScript code that non-REST events can invoke. For example, execute the code when the server starts up or when a message is received on a given connection. You define how listeners respond to events. For example, a time-based listener can trigger the insertion of a row in a database or a system can process a message that it receives by publishing another message.
lac42
Listeners are pieces of JavaScript code that non-REST events can invoke. For example, execute the code when the server starts up or when a message is received on a given connection. You define how listeners respond to events. For example, a time-based listener can trigger the insertion of a row in a database or a system can process a message that it receives by publishing another message.
Typical uses of listeners include:
  •  
    Microservices.
     Microservices are autonomous and independent. For example, Service-1 requires access to Service-2, even when it is down. Some brokers, such as MQTT and Kafka, provide message queuing for delayed delivery. You can use listeners to process these messages.
    A typical listener might accept the message, convert to a JSON/XML string, and invoke the 
    listenerUtil.restPOST/PUT
     method. This method activates interface logic, which then activates declarative business logic.
    The 
    Publish and subscribe to messages
     use case applies to this approach to using listeners.
    For more information:
  •  
    Internet of Things (IoT).
     IoT devices use MQTT. You can establish listeners to handle these messages. Typical IoT processing persists the message. You can modify or validate inbound data, with extra automation (persistence and object model), by declaring event rules.
  •  
    DevOps.
     
    CA Live API Creator
     can also invoke listeners when the server starts. You can then register with a service discovery platform, such as Consul, or self-configure the server (for example, set data source connection parameters).
In this article:
 
 
Workflow
The following diagram shows the workflow for creating a listener in API Creator:
create a listener_new
create a listener_new
Connections
Connections are a set of properties that defines how to connect to an external system. MQTT, Kafka, RabbitMQ, and Java Message Service (JMS) listeners require a connection.
For more information about connections, see Create Connections.
Listener Types
You can create the following types of listeners in API Creator.
MQTT Listeners
MQTT listeners execute JavaScript code based on the arrival of messages to a specific topic in  MQTT brokers.
For information about how to create MQTT listeners, see MQTT Listeners.
Kafka Listeners
Kafka listeners execute JavaScript code based on the arrival of messages to a specific topic in Kafka brokers.
For information about how to create Kafka listeners, see Kafka Listeners.
RabbitMQ Listeners
RabbitMQ listeners execute JavaScript code based on the arrival of messages to a specific queue and exchange in a RabbitMQ broker.
For information about how to create RabbitMQ listeners, see RabbitMQ Listeners.
JMS Listeners
JMS listeners execute JavaScript code based on the arrival of messages to a specific topic in a JMS broker or brokers.
For information about how to create JMS listeners, see JMS Listeners.
Startup and Shutdown Listeners
Startup listeners are pieces of JavaScript that 
CA Live API Creator
 invokes whenever you start API Server. More specifically, API Server executes the startup listener JavaScript code every time the 
CA Live API Creator
 WAR file starts. If the infrastructure support engineer or the system administrator restarts the 
CA Live API Creator
 WAR file, 
CA Live API Creator
 again executes the startup listener JavaScript code.
If have configure 
CA Live API Creator
 to run as a cluster, 
CA Live API Creator
 executes the JavaScript code on each node as it starts.
Shutdown listeners are the mirror image of startup listeners. 
CA Live API Creator
 invokes shutdown listeners whenever you stop API Server.
 If the Java container (for example, Apache Tomcat, Jetty, IBM WebSphere, or Oracle WebLogic) suffers a serious failure, 
CA Live API Creator
 might not invoke shutdown listeners upon shutdown.
For more information:
Listener Logs
 
CA Live API Creator
 generates logs for listener code that use the 
log
 object in JavaScript scope. You can access these logs by persisting your 
CA Live API Creator
 log messages. You can persist log messages by creating a logger for externalizing your API logs.
For more information about how to persist log messages, see External Logging.
Listener Status
Listeners are either active or inactive. Active listeners are enabled in the API and inactive listeners are disabled in the API. If the listener is enabled in the API (it is active), API Server executes the listener code when it receives messages. You can mark a listener as active or inactive by selecting or clearing the 
Active
 checkbox.
Listeners in the "Running" status have initialized themselves successfully based on the connection that you configured. Listeners in the "Stopped" status have issues with the configured connection, with the listener parameters, or with the code.
 You can view the listener status from the status icon that appears at the top of the page in API Creator. The following image shows a startup listener in the "Stopped" status:
  Screen Shot 2017-09-22 at 4.39.28 PM.png  
The status is based on the following factors:
  • The validity of the parameters.
  • The status of the underlying connection.
  • Exceptions in the listener code that are causing the connection to fail.
 Troubleshoot listener issues using the log entries. Click 
Refresh
 or select the 
Auto-refresh
 checkbox.
You can also view a listener's status using the icon that displays to the left of the listener name in the list of listeners:
Icon
Listener Status
The listener is in the "Running" status and is active.
The listener is in the "Stopped" status and is active.
The listener is in the "Stopped" status and is inactive.