ImaPlugin (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin

## 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.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

    - #### LOG_CRIT

          static final int LOG_CRIT

      The log entry is critical
      See Also:
        Constant Field Values

    - #### LOG_ERROR

          static final int LOG_ERROR

      The log entry represents an error
      See Also:
        Constant Field Values

    - #### LOG_WARN

          static final int LOG_WARN

      The log entry represents a warning
      See Also:
        Constant Field Values

    - #### LOG_NOTICE

          static final int LOG_NOTICE

      The log entry is important but is not an error
      See Also:
        Constant Field Values

    - #### LOG_INFO

          static final int LOG_INFO

      The log entry is informational
      See Also:
        Constant Field Values

  - ### 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