Startup Listeners

API Server executes the JavaScript code that is defined for the startup listener each time  starts. More specifically, API Server executes the listener every time the WAR file starts. If the API Server system administrator or the infrastructure support engineer restarts the  WAR file, API Server executes the startup listener again.
lac53
API Server executes the JavaScript code that is defined for the startup listener each time 
Layer7 Live API Creator
 starts. More specifically, API Server executes the listener every time the WAR file starts. If the API Server system administrator or the infrastructure support engineer restarts the 
Layer7 Live API Creator
 WAR file, API Server executes the startup listener again.
You can create startup listeners that signal to a registry (for example, Consul) that the server is up, that log an event to an outside system, or that configures the API based on an outside source of information, such as a file or a directory system.
As API Server executes the listener, it creates an entry in the log. You can view the list of logs on the Logs tab. You can filter the list of logs by time and by listener name, refresh the list, and delete all logs.
In this article:
2
Create a Startup Listener
  1. With your API open, in the Create section, click 
    Listeners
    .
    If you have not created a listener yet, the Welcome to Listeners and Connections page displays. If you have a listener created already, the Details tab on the Listeners page displays.
  2. Do one of the following:
    • If you have not created a listener yet, create a listener by clicking 
      Create a Listener
      .
    • If you have a listener created already, above the list of listeners, click 
      Add
      .
  3. Complete the following fields, and then save your changes:
    Listener name
    Defines the listener name.
    Default: 
    New Listener
    Example:
     
    Register with Consul
    Listener type
    Defines the listener type. Select 
    Startup
    .
    Options:
     Startup, Shutdown, MQTT, KafkaConsumer, and KafkaProducer
    Default:
     Startup
    One server only
    (This option is for when you have configured 
    Layer7 Live API Creator
     to run as a cluster.) Select this option if you want 
    Layer7 Live API Creator
     to execute the listener code on a node in the cluster instead of on all nodes in the cluster. 
    Layer7 Live API Creator
     records the node on which it executed the listener code in the listener log.
    Prerequisite:
     You have configured Hazelcast for cluster synchronization strategy. For more information, see Configure to Run as a Cluster.
    All servers
    Select this option if you want
    Layer7 Live API Creator
     to execute the listener code on all nodes in the cluster. 
    Logging level
    Defines the level at which the listener outputs messages to its logs. The messages that appear in the log are only the messages that are logged at a level equal to or superior to this logging level. For example, if the listener has a logging level of 
    Info
     (
    log.info("Foo")
    ), then the following code has no effect, because the listener's logging level of 
    Info
     is a higher logging level than 
    Debug
    :
    log.debug('This is a log message');
    Values:
      • Off:
         The listener does not output messages to the log.
      • Error:
         The listener outputs only serious errors to the log.
      • Warning:
         The listener outputs serious errors, including warnings, to the log.
      • Info:
         The listener outputs serious errors–including warnings and information messages–to the log.
      • Debug:
         The listener outputs serious errors–including warnings, information messages and high-level debug messages–to the log.
      • Finer:
         The listener outputs serious errors–including warnings, information messages, high-level debug messages, and medium-level debug messages–to the log.
      • Finest:
         The listener outputs serious errors–including warnings, information messages, high-level debug messages, medium-level debug messages, and low-level debug messages–to the log.
    Default:
     Warning
    Active
    Indicates whether the startup listener is active and
    Layer7 Live API Creator
     can execute it. Controlling their state can be useful during development, or if you want to disable the listener without deleting it.
    Default: 
    Cleared
  4. Click the 
    Code
     tab, enter the JavaScript code that 
    Layer7 Live API Creator
     executes each time 
    Layer7 Live API Creator
     starts, and then click 
    Save
    .
    You can use the following JavaScript objects inside the listener code:
    • The 
      listenerUtil
       object
      For information about this object, see The listenerUtil Object.
    • The 
      log
       object
      For information about this object, see The log Object.
    • The 
      JSON
       object. The standard JavaScript object for converting objects to and from JSON strings.
      You can view a list of the available methods that you can use in your JavaScript code using code completion. For more information about code completion, see Code Completion.
  5. Click the 
    Details
     tab, select the 
    Active
     checkbox, and then click 
    Save
    .
Your startup listener is created and is active.
Example: Create a Startup Listener that Registers a Service with a Consul Cluster
Consul is a popular service discovery mechanism which allows for dynamic lookup of services. The following example is a real-world example of how to use a startup listener. In this example, whenever a server starts up with your API, you want to make sure that Consul is aware of it, so that it can refer other systems to it.
For more information about Consul, see the Consul documentation.
Use the following process to create a listener that registers a service with a Consul cluster:
Create a Startup Listener
Create a startup listener called 
Register with Consul
 and
Startup
 as the listener type.
Enter the Startup Listener Code
  1. With your startup listener open, click the
    Code
    tab.
  2. Enter the following code in the code editor, and then save your changes:
    var NewService = Java.type("com.ecwid.consul.v1.agent.model.NewService");
    var newService = new NewService();
    newService.setId("lac01");
    newService.setName("Live API Creator");
    newService.setTags(["My Live API Creator API", "Awesome"]);
    newService.setPort(8080);
    // Optional: add a service check so that Consul can check the health of the service
    var check = new NewService.Check();
    // The @heartbeat URL is handy because it does not require authentication, you could use
    // an unauthenticated custom endpoint too.
    check.setHttp("http://" + listenerUtil.getHostName() + ":8080/rest/abl/admin/v2/@heartbeat");
    check.setInterval("60s");
    newService.setCheck(check);
    var ConsulClient = Java.type("com.ecwid.consul.v1.ConsulClient");
    var client = new ConsulClient("localhost");
    client.agentServiceRegister(newService);
  3. Ensure that it is correct for your specific situation. For example, the Consul server name can be
    localhost
    (as in this example) if you are running Consul on the same machine as
    Layer7 Live API Creator
    . In production system, this might not be the case. If you are not  running 
    Layer7 Live API Creator
     on port 8080, change the value in the code editor.
For more details about the consul-api API options and features, see the consul-api API documentation.
Install the Required Java Libraries
Prerequisite:
You have installed the Java library.
How you install the library depends on the platform you are running 
Layer7 Live API Creator
. For Apache Tomcat and Jetty, copy the following libraries to the
lib
directory:
These libraries are indirect dependencies of the 
 Java library.
Start the Startup Listener
Marking your startup listener as active automatically starts the listener.
Follow these steps:
  1. With your startup listener open, click the
    Details
    tab.
  2. Select the
    Active
    checkbox, and then save your changes.
     If the listener was already marked as active, clear this checkbox, save your changes, select this checkbox, and then save the changes again.
The listener starts.
Verify that the Startup Listener Ran Successfully
A successful startup is indicated by a log entry with a name similar to
Listener was started: Register with Consul
, and an empty log (unless you added some logging of your own to the code).
Look at your Consul directory and verify that the registration was successful.
Follow these steps:
  1. With your startup listener open, click the 
    Logs
     tab.
  2. If needed, click
    Refresh
    .
  3. Locate and select the startup log for your new listener, and make sure that it does not contain any errors.
    Example:
    A common error might look something like:
    Listener failed to start: Register with Consul 
    java.lang.ClassNotFoundException: org.apache.http.conn.HttpClientConnectionManager 
    at java.net.URLClassLoader.findClass(URLClassLoader.java:381) 
    etc...
    This specific error message indicates that the Apache HTTP Client library is not available.
    For more information about how to install the Java libraries, see the "Install the Required Java Libraries" section.
You have created the startup listener.