Interface ImaPlugin


  • public interface ImaPlugin
    A plug-in interface defines a set of methods which can be invoked for this plug-in. The object is sent to the plug-in on the initialize() callback.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String COPYRIGHT  
      static int LOG_CRIT
      The log entry is critical
      static int LOG_ERROR
      The log entry represents an error
      static int LOG_INFO
      The log entry is informational
      static int LOG_NOTICE
      The log entry is important but is not an error
      static int LOG_WARN
      The log entry represents a warning
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      ImaConnection createConnection​(String protocol, String endpoint)
      Create an internal virtual connection.
      ImaMessage createMessage​(ImaMessageType mtype)
      Create a message.
      String getAuthor()
      Get the author field of the plug-in.
      String getBuild()
      Get the build field of the plug-in.
      Map<String,​Object> getConfig()
      Get the plug-in configuration properties.
      String getCopyright()
      Get the copyright field of the plug-in.
      String getDescription()
      Get the description field of the plug-in.
      String getLicense()
      Get the license field of the plug-in.
      String getName()
      Get the plug-in name.
      String getProtocolFamily()
      Get the protocol family of the plug-in.
      String getTitle()
      Get the title field of the plug-in.
      String getVersion()
      Get the version field of the plug-in.
      boolean isTraceable​(int level)
      Check if trace is allowed at the specified level.
      void log​(String msgid, int level, String category, String msgformat, Object... args)  
      void trace​(int level, String message)
      Trace with a level specified.
      void trace​(String message)
      Trace unconditionally.
      void traceException​(int level, Throwable ex)
      Write an exception stack trace to the trace file at a specified level.
      void traceException​(Throwable ex)
      Unconditionally write an exception stack trace to the trace file.
    • Method Detail

      • createConnection

        ImaConnection createConnection​(String protocol,
                                       String endpoint)
        Create an internal virtual connection.

        Most plug-in methods are done in service of a connection. In most cases the connection results from a client connecting to the IBM MessageSight server, but in some cases the plug-in needs to create its own virtual connection.

        An internal connection is used as a virtual connection when there is no physical connection created by a client connecting to the IBM MessageSight server. An internal connection can be used to subscribe and receive messages, but no data will come on the connection and no data may be sent to the connection.

        At some point after making this call the plug-in will receive an OnConnection() for this connection, and must set identity and authenticate before the connection can be used. This is commonly done during the zero length onData callback which follows the onConnection. It is common for a plug-in to self-authenticate virtual connections but it must still call the setIdentity or authenticate methods and receive a onConnected response before the connection can be used to subscribe and send messages.

        A virtual connection must have a unique clientID. If the virtual connection does not have any durable subscriptions is can generate a unique clientID which is normally done by starting the clientID with an underscore, the second character not being an underscore, and containing some number of random characters or digits. A virtual connection may use a clientID starting with two underscores which indicates a system clientID. It must however be careful to avoid any conflict with the clientID encodings of other system components.

        A virtual connection is associated with an endpoint. THe endpoint must exist but it is not requiered to be enabled. The endpoint allows messaging policies to be attached and provides for statistics.

        Parameters:
        protocol - The name of the protocol
        endponit - The name of the endpoint used for authentication
        Returns:
        The connection which is created
      • createMessage

        ImaMessage createMessage​(ImaMessageType mtype)
        Create a message.

        Create a message of the specified message type. Additional ImaMessage methods are then called to set the contents of the message.

        Parameters:
        mtype - The message type of the message
        Returns:
        The message which is created
      • getConfig

        Map<String,​Object> getConfig()
        Get the plug-in configuration properties.

        The configuration properties come from the plugin.json definition file for the plug-in. and can be modified later.

        Note: Currently, modifying the original configuration properties is not supported. If you call this method, only the values set at install time will be used.

        Returns:
        A map object with a set of configuration properties
      • getName

        String getName()
        Get the plug-in name.
        Returns:
        The name of the plug-in
      • getProtocolFamily

        String getProtocolFamily()
        Get the protocol family of the plug-in.

        The protocol family is used define authorization and is commonly the name for a group of related protocols. This could be for instance multiple versions of a protocol. A plug-in defines a single protocol family, but can define multiple protocols.

        Returns:
        The protocol family of the plug-in.
      • getAuthor

        String getAuthor()
        Get the author field of the plug-in.
        Returns:
        The author field or null if it is not set
      • getVersion

        String getVersion()
        Get the version field of the plug-in.
        Returns:
        The version field or null if it is not set
      • getCopyright

        String getCopyright()
        Get the copyright field of the plug-in.
        Returns:
        The copyright field or null if it is not set
      • getBuild

        String getBuild()
        Get the build field of the plug-in.
        Returns:
        The build field or null if it is not set
      • getDescription

        String getDescription()
        Get the description field of the plug-in.
        Returns:
        The description field or null if it is not set
      • getLicense

        String getLicense()
        Get the license field of the plug-in.
        Returns:
        The license field or null if it is not set
      • getTitle

        String getTitle()
        Get the title field of the plug-in.
        Returns:
        The title field or null if it is not set
      • log

        void log​(String msgid,
                 int level,
                 String category,
                 String msgformat,
                 Object... args)
      • isTraceable

        boolean isTraceable​(int level)
        Check if trace is allowed at the specified level.

        Parameters:
        level - the trace level
        Returns:
        true if the level is allowed to trace
      • trace

        void trace​(int level,
                   String message)
        Trace with a level specified.
        Parameters:
        level - the level (1-9)
        message - the message
      • trace

        void trace​(String message)
        Trace unconditionally.
        Parameters:
        message - - the message
      • traceException

        void traceException​(Throwable ex)
        Unconditionally write an exception stack trace to the trace file.
        Parameters:
        ex - The exception
      • traceException

        void traceException​(int level,
                            Throwable ex)
        Write an exception stack trace to the trace file at a specified level.
        Parameters:
        level - The level
        ex - The exception