Developing a protocol plug-in

You can use protocol plug-ins to add industry-specific messaging protocols to Eclipse Amlen in a controlled way that does not compromise the security of the server environment. The protocol plug-in can also support existing sensors that are not able to change to MQTT. You can write your own protocol plug-ins to use with Eclipse Amlen by using the Eclipse Amlen protocol plug-in SDK. The protocol plug-in facility is not available in high availability environments.

Download and extract the contents of the SDK bundle. Then, follow the instructions in ImaTools/ImaPlugin/README.txt to import the sample plug-in projects that are provided with the SDK bundle.

Download and install one of the following supported versions of Java™:
  • IBM® SDK, Java Technology Edition, Version 7 (64-bit)
  • Oracle Java SE Development Kit, Version 7 (64-bit)

You can use the Eclipse Amlen protocol plug-in SDK to extend Eclipse Amlen protocol support beyond the protocols that are natively supported. Use the SDK to write Java plug-ins that you can then deploy in Eclipse Amlen.

If you want to write your own protocol plug-in to use with Eclipse Amlen, you need to develop the following files:
  • A plug-in configuration file that is written in JSON
  • A set of JAR files to implement the plug-in
All of these files must be at the root level of the .zip archive.
  1. Implement the ImaPluginListener and ImaConnectionListener interfaces and create one or more JAR files that contain the classes that you implemented.

    ImaPluginListener interface.
    The ImaPluginListener interface provides callbacks that allow custom protocol implementations to be associated with an ImaPlugin object that is provided by Eclipse Amlen. Refer to the Javadoc™ information that is provided with the SDK for complete details about the methods that need to be implemented for these interfaces.

    • The initialize() method is used to start the custom protocol implementation when Eclipse Amlen is started.
    • The terminate() method is used to stop the custom protocol implementation when Eclipse Amlen shuts down.
    • The startMessaging() method is used to run any protocol-specific tasks that are required after the Eclipse Amlen messaging engine is started.
    • The onProtocolCheck() method is used to determine whether a connection belongs to the protocol. If a connection belongs to the protocol, the ImaPluginListener enables the protocol to instantiate an implementation of the ImaConnectionListener interface with the onConnection() method that associates the newly accepted ImaConnection object with the protocol.
    • The onConnection() method is used when a new connection with a known protocol, such as WebSockets or HTTP, is found.
    • The onConfigUpdate() method is used when the configuration of the plug-in is updated.
    • The onAuthenticate () method is not called.

    ImaConnectionListener interface.
    The ImaConnectionListener interface allows a connection to be associated with a custom protocol by using the ImaConnection object that is received from Eclipse Amlen. The ImaConnectionListener interface provides callbacks for managing connections to the custom protocol after the protocol plug-in accepts a connection.

    • The onConnected() method is used to take appropriate actions when a connection is established.
    • The onClose() method is used to take appropriate actions when a connection is closed.
    • The onData() or onHttpData() method is used to manage communication activities such as handling incoming data.
    • The onMessage() method is used to handle messages that are received from Eclipse Amlen.
    • The onComplete() method is used to acknowledge the completion of a publish or subscribe operation.
    • The onLivenessCheck() method is used to check whether the connection is still active.
    • The onHttpData() method is used when an HTTP header is received on the connection.
    • The onGetMessage() method is used as a result of an ImaConnection.getRetainedMessage() operation and returns the retained message for the specified topic if one exists.
  2. Create a plugin.json descriptor file for the new plug-in.
    The plugin.json descriptor file provides information to Eclipse Amlen about the plug-in so that it can be started when Eclipse Amlen is started. While the descriptor supports several configuration properties, four property values must be specified for any protocol plug-in that you implement. These values are Name, Protocol, Class, and Classpath.
    • The Name property specifies the plug-in name and must be unique.
    • The Protocol property specifies a protocol family. Each plug-in represents a protocol. However, multiple plug-ins can be associated with a single protocol family. Protocol families allow multiple protocols to share authorization rules that are based on endpoint configuration and on connection and messaging policies. For example, MQTT over TCP and MQTT over WebSockets protocols share the same authorization rules as MQTT.
    • The Class property must contain the name of the class that implements the ImaPluginListener interface. This class name must include the complete, dot separated path to the class.
    • The Classpath property must include the full list of JAR files that implement the protocol plug-in that is represented as a JSON array of strings. All JAR files that are used by the plug-in must appear in the Classpath property so that they can be loaded by Eclipse Amlen.
    The following table shows the complete list of properties that can be used in the descriptor file:
    Table 1. Properties of a plug-in configuration file
    Name Type Default Description
    Class String required The name of the initial class to load for a plug-in. This class must be an instance of ImaPluginListener. This value must be a valid Java package name and class name, which is separated by dots.
    Classpath String Array required A set of JAR files that contain the Java classes that are needed for the plug-in. The path must not be included, and the JAR files must be in the root directory of the .zip file that is used to define the plug-in. These JAR files are used only by this plug-in, and use a separate directory and class loader for each plug-in. The JAR files in the list must exist in the .zip file that is used for installation.
    InitialByte Array none (required for TCP connections) A set of initial bytes that can be specified as an array of strings of length 1 byte or as integers of the value 0-255. A single entry with the value ALL indicates that any initial byte is selected. If this value is not specified or the array is empty, then TCP connections are not accepted.
    Name String required The name of the plug-in. This name must be unique among all installed plug-ins. The name is limited to 64 characters and must be a valid Java name. It can start with any alphabetic character, currency symbol, or underscore, and continue with any such character or a digit.
    Properties Object none A set of properties that are sent to the plug-in as configuration. The names and types of the properties are not known to the Eclipse Amlen server
    Protocol String required The protocol family against which to authorize. Each plug-in represents a single protocol family, but the same protocol family can be used by several plug-ins. The plug-in can also use one of the system protocol families. All policy checking for protocol is done based on this protocol. The maximum length of the name is 32 characters.
    UseBrowse Boolean false The protocol uses queue browser function.
    UseQueue Boolean false The protocol uses queue send and receive.
    UseTopic Boolean true The protocol uses publish/subscribe topic support.
    WebSocket String array none (required for WebSockets connections) An array of WebSockets subprotocols supported by this plug-in. The subprotocols are checked in a case independent manner and must be unique among the installed plug-in set. If this property is missing or the array is empty, then no WebSockets protocol can connect to this plug-in. The maximum length of the name is 64 characters. The name must contain only ASCII-7 characters not including control characters (0x00 to 0x1F and x07F), space, or the separator characters '()<>[]{},;:\/?=".
  3. Create a .zip archive that contains the JAR file or files and the plugin.json descriptor file.
    Note:

    To deploy your protocol plug-in, you must create a .zip archive file that contains the JAR file (or files) from step 1 and the plugin.json file from step 2. All of these files must appear at the root level of the .zip archive so that they can be loaded.

An example of a plug-in configuration file for JSON-based messaging. 
/*
 * Sample plug-in configuration file for JSON based messaging
 */
 {    
    "Name":        "json_msg",
    "Description": "A sample plug-in for JSON based messaging",
    "Protocol":    "json_msg",
    "Classpath":   [ "jsonprotocol.jar" ],
    "Class":       "com.ibm.ima.samples.plugin.jsonmsg.JMPlugin",
    "WebSocket":   [ "json-msg" ],
    "InitialByte": [ "{" ],  /* The json_msg always starts with a JSON object */
    "UseQueue":    false,    /* This plug-in does not implement queues */
    "UseTopic":    true,     /* This plug-in implements topics */
    "Properties":  {
         "Debug": true    
    }
 }
Apply your plug-in to Eclipse Amlen. For more information about installing or updating a protocol plug-in, see Creating and updating a protocol plug-in.