ImaPluginListener (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin

## Interface ImaPluginListener

-     public interface ImaPluginListener

  The ImaPluginListener defines a set of callback methods which are called by MessageSight. The plug-in must implement these methods.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `COPYRIGHT` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `initialize​(ImaPlugin plugin)` | Callback when the plug-in is loaded.
    `boolean` | `onAuthenticate​(ImaConnection connect)` | Callback to request authentication of a connection.
    `void` | `onConfigUpdate​(String name, Object subname, Object value)` | Callback for a configuration update.
    `ImaConnectionListener` | `onConnection​(ImaConnection connect, String protocol)` | Callback for a new connection with a known protocol.
    `int` | `onProtocolCheck​(ImaConnection connect, byte[] data)` | Callback when a new connection is detected which might be for this plug-in.
    `void` | `startMessaging​(boolean active)` | Callback when messaging is started within the server.
    `void` | `terminate​(int reason)` | Callback to inform the plug-in it should release resources.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### initialize

          void initialize​(ImaPlugin plugin)

      Callback when the plug-in is loaded. This is called early in the startup of the plug-in process. Methods which use messaging function will not work correctly until the startMessaging callback is invoked.

      It is expected that the plug-in will save the ImaPlugin object for later use.

      Parameters:
        `plugin` - The plug-in object which contains methods which the plug-in can call for services.

    - #### onAuthenticate

          boolean onAuthenticate​(ImaConnection connect)

      Callback to request authentication of a connection.

      Note that this function is not currently implemented and will not be called. For future compatibility the plug-in should return false.

      This connection may have been accepted by this or any other protocol.

      The connection is blocked (will not process data) until it has been authenticated.

      If this method returns true, the plug-in is required to call the ImaConnection methods authenticate() or setIdenity() with an auth option on the specified connection. This can be done either before returning from this callback or later. If this method returns false, authentication processing is continued using other authenticators.

      Parameters:
        `connect` - The connection to authenticate
      Returns:
        true if this plug-in has or will authenticate this connection, false otherwise.

    - #### onProtocolCheck

          int onProtocolCheck​(ImaConnection connect,
                              byte[] data)

      Callback when a new connection is detected which might be for this plug-in. This method allows the plug-in to choose whether this connection belongs to it. The check should be as specific as possible with the fewest possible bytes.

      If this callback returns 0 the connection is accepted. If it returns a negative value the connection is not accepted. If it returns a positive value, this indicates the number of bytes of data it needs to determine if the connection belongs to it. If another plug-in accepts the connection before more data is available, this method will not be reinvoked.

      The data commonly has the first record sent by the client, but is only guaranteed to have a single byte.

      Before returning, this method may set the protocol name in the connection using the connect.setProtocol() method. If it does not do so, the name of the plug-in will be used as the protocol.

      Parameters:
        `connect` - The connection object
        `data` - Data from the first packet received
      Returns:
        0=accept, <0=not accepted, >0=amount of data needed to accept

    - #### onConnection

          ImaConnectionListener onConnection​(ImaConnection connect,
                                             String protocol)

      Callback for a new connection with a known protocol.

      This is called when a connection is known to be accepted by this plug-in. This can either be due to returning a zero value from onProtocolCheck(), or using a framer like WebSockets which declares the protocol.

      If the plug-in is unwilling to accept this connection this method should return null.

      Parameters:
        `connect` - The connection object
        `protocol` - The protocol of the connection
      Returns:
        A connection listener object associated with this connection

    - #### onConfigUpdate

          void onConfigUpdate​(String name,
                              Object subname,
                              Object value)

      Callback for a configuration update.

      When a protocol is created it has a set of properties which it can receive using ImaPlugin.getConfig(). This method allows the plug-in to be notified when a property changes.

      Note: This method is not currently invoked.

      Parameters:
        `name` - The name of the property
        `subname` - If the base property is a Map object, the name of the inner property.
        `value` - The value of the property

    - #### startMessaging

          void startMessaging​(boolean active)

      Callback when messaging is started within the server. Some actions cannot be taken by the plug-in before messaging starts.
      Parameters:
        `active` - Specifies whether this server instance is the active peer or the backup in a high availability pair, true for active and false for backup.

    - #### terminate

          void terminate​(int reason)

      Callback to inform the plug-in it should release resources. There is no guarantee that this is called, but either it will be called or the JVM running the plug-in will be terminated.
      Parameters:
        `reason` - The reason for the close as a return code. 0=normal