ImaConnectionListener (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin

## Interface ImaConnectionListener

-     public interface ImaConnectionListener

  The connection listener defines the callbacks associated with a connection. The plug-in which accepts a connection must create an implementation object which implements this interface, and return that on the call to onConnection() in the plug-in listener.
  The object implementing this interface is the connection related object owned by the plug-in.

- - ### 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` | `onClose​(int rc, String reason)` | Called when the connection is closing.
    `void` | `onComplete​(Object obj, int rc, String message)` | Called when an asynchronous action completes.
    `void` | `onConnected​(int rc, String reason)` | Called when the connection request completes.
    `int` | `onData​(byte[] data, int offset, int length)` | Called when data is available on a connection.
    `void` | `onGetMessage​(Object correlate, int rc, ImaMessage message)` | Called when an asynchronous get retained message action completes.
    `void` | `onHttpData​(String op, String path, String query, String content_type, byte[] data)` | Called when data is received on an HTTP connection.
    `boolean` | `onLivenessCheck()` | Called when no data was received on the connection during checkAlive timeout.
    `void` | `onMessage​(ImaSubscription sub, ImaMessage msg)` | Called when a message from MessageSight is received for a connection.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### onClose

          void onClose​(int rc,
                       String reason)

      Called when the connection is closing. It is possible that the physical connection is already closed when this method is called. Otherwise the physical connection will be closed after the return from this callback. This provides the ability to clean up any resources attached to the connection.
      Parameters:
        `rc` - A return code 0=normal
        `reason` - A human readable reason code

    - #### onData

          int onData​(byte[] data,
                     int offset,
                     int length)

      Called when data is available on a connection. If the onData() callback throws an exception, the connection is terminated.
      Parameters:
        `data` - The available data
      Returns:
        The number of bytes used. If this is negative or greater than the number of bytes in the data then all of the bytes are consumed. Otherwise it is the number of bytes used and the remaining bytes will be resent on the next onData call when there is more data available.

    - #### onMessage

          void onMessage​(ImaSubscription sub,
                         ImaMessage msg)

      Called when a message from MessageSight is received for a connection. When a message is received there is almost always an active subscription which is the reason the message is received. However this is not guaranteed. For instance a message might arrive after a subscription is closed because the message processing is asynchronous. In this case the subscription is returned as null so this case needs to be handled.
      Parameters:
        `sub` - The subscription on which the message comes. This can be null.
        `msg` - The message

    - #### onComplete

          void onComplete​(Object obj,
                          int rc,
                          String message)

      Called when an asynchronous action completes. Since the completion object can be something other than an ImaMessage, the callback should always check the class of the object before casting it.
      Parameters:
        `obj` - The object which is complete. For the completion of a send, the object is the message which was sent.
        `rc` - The return code. 0=good
        `message` - A human readable message

    - #### onConnected

          void onConnected​(int rc,
                           String reason)

      Called when the connection request completes. When this method is called, all authentication and authorization of the connection is complete. If the return code is 0 the connection can be used.
      Parameters:
        `rc` - A return code 0=normal
        `reason` - A human readable reason code

    - #### onLivenessCheck

          boolean onLivenessCheck()

      Called when no data was received on the connection during checkAlive timeout. This is commonly called as the result of a keepalive timeout. It can also be called when another connection uses the same ClientID as this connection.
      Returns:
        true if connection should be left active, false if connection should be closed

    - #### onHttpData

          void onHttpData​(String op,
                          String path,
                          String query,
                          String content_type,
                          byte[] data)

      Called when data is received on an HTTP connection.

      Additional information (such as host name, headers, and cookies) is available by query from the connection.

      Note: this is currently not implemented

      Parameters:
        `op` - The operation to perform ("GET", "PUT", or "POST")
        `path` - The path not including the alias used to route to this plug-in
        `query` - The query section of the URI, not including the leading question mark
        `content_type` - The content type from a PUT or POST operation. This might be NULL.
        `data` - The byte data from a PUT or POST operation

    - #### onGetMessage

          void onGetMessage​(Object correlate,
                            int rc,
                            ImaMessage message)

      Called when an asynchronous get retained message action completes.
      Parameters:
        `obj` - The correlate object.
        `rc` - The return code. 0=good
        `msg` - The message. If the return code is not zero, this parameter will null.