Manage Listener Providers

Listener providers are sets of JavaScript code that you define that implement the extensible listener provider framework. You manage listeners providers by adding them, by specifying their connections, and by defining the code for them.
lac52
Listener providers are sets of JavaScript code that you define that implement the extensible listener provider framework. You manage listeners providers by adding them, by specifying their connections, and by defining the code for them. Add listener providers when you require interfaces with external systems. Listener providers enable the code interface in 
CA Live API Creator
 that either listens to events from external systems or triggers events to other systems. The code interface allows 
CA Live API Creator
 to leverage listener providers and integrate them within your API.
They are system-level objects that are available to all TeamSpaces.
CA Live API Creator
 includes listener providers that you can use as a starting point to adding your listener provider.
For more information about these providers, see the "Available Listener Providers" section.
For more information about how to create listeners and the available listener providers, see Creating Listeners.
In this article:
 
 
Add Listener Provider Workflow
The following diagram show the workflow for adding a listener provider in API Creator:
listenerproviderlifecycle.png
Verify the Prerequisites
Before you can add a listener provider, verify that you have completed the following prerequisite steps:
  • You have some programming expertise.
  • You have added the JAR files that you want to implement and call from the listener provider's JavaScript code. 
  • You have installed the JAR driver and restarted API Server.
    • If you have installed the self-contained, single-user version of 
      CA Live API Creator
       that is based on Jetty, copy the JDBC driver into the 
      %JETTY_HOME%/caliveapicreator/lib/ext
       directory.
    • If you have installed 
      CA Live API Creator
       on Tomcat, copy the JAR files into the 
      %{CATALINA_HOME}/lib
       directory. 
  • You have system administrator (
    sa
    ) user privileges in 
    CA Live API Creator
    .
Add a Listener Provider
You can add a listener provider using API Creator into 
CA Live API Creator
. The following procedure explains how to add a listener provider using API Creator.
Follow these steps:
  1. Log in to API Creator as a system administrator (
    sa
    ) user.
  2. Click the 
    Listener Providers
     tab. 
  3. Click 
    Add
    .
    The listener provider is added.
  4. Enter a name and comment for the listener provider, and then save your changes. By default, the listener provider is active (the 
    Active
     checkbox is selected) and is defined as a provider that can connect to outside systems to listen to messages or to publish to outside systems (the 
    Can have connections
     checkbox is selected).
    For more information about connections and connection types, see Manage Connections.
The listener provider is added.
Define the Code for the Listener Provider
Define the code that instructs how the listener provider behaves at each processing stage of the listener.
Follow these steps:
  1. With the listener provider open, click the 
    Code
     tab.
  2. Select the code type for the code that you are defining for this listener provider. By default, 
    Startup
     is selected.
    Options:
     Startup, Shutdown, Start a connection, Test/Verify a connection, Stop a connection, Start a listener, Stop a listener, Publish Messages
    Default:
     Startup
  3. Define the code for the listener provider, and then save your changes:
    Use code completion to discover the objects and methods you can add to your code.
    Startup listener code
    The startup code instructs how 
    CA Live API Creator
     should use this listener provider during the bootstrap process. 
    Advanced users:
     You can define Camel processors and assign them to the 
    env
     variable within the code for the listener provider.
    (Optional) Shutdown listener code
    The shutdown code what happens to the listener provider when API Server is stopped.
    Start a connection listener code
    The Start a connection code instructs how 
    CA Live API Creator
     should use this listener provider to start a connection. For Camel connections, the code must return the initialized 
    CamelContext
     . The code must return an object that contains the 
    camelContext
     property assigned to an active 
    CamelContext
     instance.
    Test/Verify a connection listener code
    The Test/Verify a connection listener code instructs how 
    CA Live API Creator
     should test/verify a connection within the listener provider. This listener code is applicable only when a connection exists.
    Start a listener listener code
    The Start a listener code instructs how 
    CA Live API Creator
     should use this listener provider to start a listener based on the parameter values and to keep in running. For Camel listeners, define a route using the 
    RouteBuilder
     class that is available as a property in the 
    env
     variable. The endpoint of the route is the 
    listenerHandler
     instance that catches the message and injects it into the scope of the listener code that is defined for the API. The source of the route is the component endpoint to which you are connecting. You can relay multiple routes that end up in the 
    listenerHandler
    .
    Stop a listener listener code
    The Stop a listener code instructs how 
    CA Live API Creator
     should use this listener provider to stop a listener. For Camel connections, define the code that stops or removes the route that has been added to the connection using the 
    context.stopRoute()
     or 
    context.removeRoute()
     methods.
    Publish messages listener code
    CA Live API Creator
     uses the Publish messages code to publish messages using the connection for this provider type. 
    CA Live API Creator
     executes this code when it calls the 
    SysUtility.publishMessage()
     method with a connection of this provider type. For Camel connections, 
    CA Live API Creator
    :
    1. Gets the Camel ProducerTemplate API from the injected CamelContext which is part of a connection object.
    2. Fetches the required parameters for publishing a message for the component from the Connection parameters.
    3. If the connection does not accept parameters, uses the options JavaScript object argument to get the same information from the caller of the 
      Sysutility.publishMessage()
       method.
    4. Publishes the message using the Camel ProducerTemplate API.
Define the Connection and Listener Parameters for the Listener Provider
Define the parameters that require values when creating a connection or listener. Connection and listener parameters are sets of configuration properties that are assigned to a connection or listener object to customize its behavior.
Load Camel Component Properties for the Connection or Listener Parameters
For Camel components, you can load the properties as per the component definition.
Prerequisite:
 The Camel component is available in the 
CA Live API Creator
 classpath.
Follow these steps:
  1. With the listener provider open, click the 
    Connection parameters
     (or 
    Listener parameters
    ) tab.
  2. Click 
    Retrieve Parameters
    . You can add a parameter by clicking 
    Add Parameter
    .
  3. Enter the schema name of the Camel component for which you are loading properties, for example, 
    file
     or 
    jms
    , and then click 
    Add
    .
    The following image shows how you can get the schema name from the Camel component documentation.
    listenerproviderlifecycle.png
    CA Live API Creator
     retrieves the connection or listener parameter properties, such as names, descriptions, and type into the listener provider.
    For more information about Camel component names, see the Apache Camel documentation.
  4. Click 
    Save
    .
The Camel component properties are loaded as connection or listener parameters.
(Optional) Define the Code Completion for the Listener Provider
You can define the context help that you get when writing the code for a listener or context-sensitive code completion. Define the code completion for listeners on the 
Code Completion
 tab for the listener provider.
For more information about how you access code completion when creating listeners, see Code Completion
For Camel connections, add the following default code completion JavaScript object:
Default code completion JavaScript object for Camel connections
return
{
message:[],
message_docs:{
type:"object",
tooltip:"html:<h3>Message</h3><p/>An implementation of <code>org.apache.camel.Message</code>. <p/>The implementation class is based on the type of the listener and consequently the Camel component."
},
payloadAsString:[],
payloadAsString_docs:{
type:"object",
tooltip:"html:<h3>payloadAsString</h3><p/>The payload of the message converted into <p/><code>java.lang.String</code>. This is done automatically by Camel during bean binding."
},
exchangeException:[],
exchangeException_docs:{
type:"object",
tooltip:"html:<h3>exchangeException</h3><p/>The <code>exchangeException</code> object is the Java representation of the exception that is thrown during an exchange. "
},
headers:[],
headers_docs:{
type:"object",
tooltip:"html:<h3>headers</h3><p/>This is a Java object containing the inbound Message headers."
},
outHeaders:[],
outHeaders_docs:{
type:"object",
tooltip:"html:<h3>outHeaders</h3><p/>This is a Java object containing the outbound Message headers."
},
properties:[],
properties_docs:{
type:"object",
tooltip:"html:<h3>properties</h3><p/>This is a Java object containing the properties of an Exchange."
},
exchange:[],
exchange_docs:{
type:"object",
tooltip:"html:<h3>exchange</h3><p/>This is a Java object that encapsulates a Camel Message during routing."+
"<p/>For more information, <a href='see'>https://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Exchange.html'>see here</a>."
},
typeConverter:[],
typeConverter_docs:{
type:"object",
tooltip:"html:<h3>typeConverter</h3><p/>This is a Java object that represents the TypeConverter that was part of the Message routing."+
"<p/>For more information, <a href='see'>https://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Exchange.html'>see here</a>."
},
camelContext:[],
camelContext_docs:{
type:"object",
tooltip:"html:<h3>camelContext</h3><p/>This is a Java object that represents the <code>Camel-Context</code>.The implementation <br/> of this context is dependent on the listener type."+
"<p/>For more information, <a href='see'>http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/CamelContext.html'>see here</a>."
}
};
(Optional) Define the Code Examples for the Listener Provider
Define the JavaScript code examples that are available from the 
Examples
 drop-down on the menu bar in code editors. API developers can insert these code examples to help them create and define listeners that use the listener provider.
(Optional) Define the Connection and Listener Documentation for the Listener Provider
Define the help text (in HTML format) that API Creator displays in the context help for the connection or listener.
To generate documentation from a specific Camel component, click 
Generate Documentation
, enter the schema name of the component from which you are generating documentation, and then click 
Add
.
View your Listener Provider Code
The code for your listener provider is located in the 
system/listener_provider
 directory in the admin repository.
For more information about this directory and the location of the admin repository, see View your API Definition.
Available Listener Providers
You can use the following listener providers that are available in 
CA Live API Creator
:
  • JMSConsumer: 
    Demonstrates connecting to Java Message Service (JMS) listeners that subscribe to messages in queues or topics in JMS-compliant providers, such as ActiveMQ and IBM MQ.
  • JMSProducer:
     Demonstrates connecting to JMSProducer connections to publish messages to queues or topics in a Java Message Service (JMS) broker.
  • KafkaConsumer:
     Demonstrates connecting to KafkaConsumer listeners, which connect to Apache Kafka brokers, listen to topics, and perform logic that is based on the arrival of messages to the topics in the Kafka brokers.
  • KafkaProducer:
     Demonstrates connecting to KafkaProducer connections to publish messages to a Kafka server.
  • MQTT:
     Demonstrates connecting to MQTT listeners, which connect to MQTT brokers, listen to topics, and perform logic that is based on the arrival of messages to the topics in MQTT brokers.
  • RabbitMQConsumer:
     Demonstrates connecting to RabbitMQConsumer connections and listeners. RabbitMQ listeners subscribe to messages in one or more queues in exchanges.
  • RabbitMQProducer:
     Demonstrates connecting to RabbitMQProducer connections to publish messages to a RabbitMQ broker for a topic.
  • Db2iDataQueue:
     Demonstrates connecting to Db2iDataQueue listeners that subscribe to messages from data queues residing on IBM Db2 for i databases.
  • Shutdown:
     Demonstrates connecting to a registry (for example, Consul) for server shutdown.
  • Startup:
     Demonstrates connecting to a registry (for example, Consul) for server startup.
If you are connecting to an FTP server to listen to and/or to create files and directories, consider using the 
FTP-Listener-Provider
 example.
For more information about this listener provider sample, see GitHub.
Next Steps
Now that you have added and defined the listener provider, you can create a listener that uses this listener provider, and then invoke the listener from your API.
For more information about how to create listeners, see Creating Listeners.