Developing a protocol plug-in

You can use protocol plug-ins to add industry-specific messaging protocols to IBM® IoT MessageSight 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 IBM IoT MessageSight by using the IBM IoT MessageSight protocol plug-in SDK. The protocol plug-in facility is not available in high availability environments.

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 IBM IoT MessageSight. 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 IBM IoT MessageSight is started.
   • The terminate() method is used to stop the custom protocol implementation when IBM IoT MessageSight shuts down.
   • The startMessaging() method is used to run any protocol-specific tasks that are required after the IBM IoT MessageSight 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 IBM IoT MessageSight. 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 IBM IoT MessageSight.
   • 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 IBM IoT MessageSight about the plug-in so that it can be started when IBM IoT MessageSight 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 IBM IoT MessageSight.

   The following table shows the complete list of properties that can be used in the descriptor 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 IBM IoT MessageSight 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.

/*
 * 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    
    }
 }