ImaConnection (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin

## Interface ImaConnection

-     public interface ImaConnection

  A connection represents a logical communications channel. The connection can represent a connection into the server, or out of the server when the server is acting as a client. It can also be a virtual connection which does not represent a physical connection. This is the Java representation of a connection object within the server. The connection holds the security context and the connection must be authenticated before it can be used. The connection is not serialized. If the connection is only processed within the ConnectionListerner methods, then no additional synchronization is required.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `Authenticated` | The connection is authenticated and authorized
    `static int` | `ContinueAuthentication` | Continue authentication check with another module
    `static String` | `COPYRIGHT` |
    `static int` | `HTTP_Option_Close` | Close the connection after sending the response.
    `static int` | `HTTP_Option_ReadMsg` | Increment the ReadMsg statistic for the connection and endpoint.
    `static int` | `HTTP_Option_WriteMsg` | Increment the WriteMsg stats for the connection and endpoint.
    `static int` | `NotAuthenticated` | The connection is not authorized and will be terminated
    `static int` | `State_Accepted` | The connection has been accepted but the not authenticated or authorized
    `static int` | `State_Authenticating` | The connection is in the process of being authenticated and authorized
    `static int` | `State_Closed` | The connection is closed
    `static int` | `State_Handshake` | The connection is in protocol handshake
    `static int` | `State_Open` | The connection ia authorized and can process messages

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `authenticate​(int auth)` | Authenticate the connection.
    `void` | `close()` | Close the connection normally.
    `void` | `close​(int rc, String reason)` | Close the connection.
    `void` | `createTransaction​(ImaTransactionListener listener)` | Create a transaction
    `void` | `deleteRetained​(String topic)` | Delete the retained message (if any) from a topic.
    `void` | `deleteRetained​(String topic, Object correlate)` | Delete the retained message (if any) from a topic.
    `void` | `destroySubscription​(Object obj, String name, ImaSubscriptionType subType)` | Destroy a subscription.
    `String` | `getCertName()` | Returns the certificate name.
    `String` | `getClientAddress()` | Returns the client IP address associated with this connection.
    `String` | `getClientID()` | Returns the client ID.
    `int` | `getClientPort()` | Returns the client port number associated with this connection.
    `ImaConnectionListener` | `getConnectionListener()` | Returns the connection listener associated with this connection.
    `ImaEndpoint` | `getEndpoint()` | Returns the endpoint associated with this connection.
    `String` | `getHttpCookie​(String name)` | Get an HTTP cookie by name.
    `Set<String>` | `getHttpCookieSet()` | Get a Set of HTTP cookie names.
    `String` | `getHttpHeader​(String name)` | Get an HTTP header from the current HTTP connection.
    `int` | `getIndex()` | Returns the index associated with this connection.
    `String` | `getPassword()` | Returns the password in obfuscated form.
    `String` | `getProtocol()` | Returns the protocol associated with this connection.
    `String` | `getProtocolFamily()` | Returns the protocol family associated with this connection.
    `void` | `getRetainedMessage​(String topic, Object correlate)` | Receive the retained message (if any) from a topic.
    `int` | `getState()` | Returns the state of the connection.
    `String` | `getUser()` | Returns the user name.
    `Object` | `getUserData()` | Returns the user data associated with the connection.
    `boolean` | `isClient()` | Returns whether this is an outgoing connection.
    `boolean` | `isInternal()` | Returns whether the connection is internal.
    `boolean` | `isReliable()` | Returns whether the connection is reliable.
    `boolean` | `isSecure()` | Returns whether the connection is secure.
    `void` | `log​(String msgid, int level, String category, String msgformat, Object... args)` | Put an entry into the log.
    `ImaSubscription` | `newSubscription​(ImaDestinationType desttype, String dest, String name, ImaSubscriptionType subType, boolean nolocal, boolean transacted)` | Create a new subscription object.
    `ImaSubscription` | `newSubscription​(String topic)` | Create a new simple subscription object.
    `void` | `publish​(ImaMessage message, String topic, Object ackObj)` | Publish a message to a topic.
    `void` | `requiredData​(int needed)` | Specify the data required before the next onData call.
    `void` | `resumeMessageDelivery()` | Resume message deliver.
    `void` | `send​(ImaMessage message, ImaDestinationType desttype, String dest, Object ackObj)` | Send a message to a destination.
    `void` | `sendData​(byte[] data)` | Send binary output data on the connection as a byte array.
    `void` | `sendData​(byte[] b, int offset, int len, boolean isText)` | Send output data on the connection
    `void` | `sendData​(String data)` | Send text output data on the connection.
    `void` | `sendHttpData​(int rc, int options, String content_type, byte[] bytes)` | Send HTTP data with options.
    `void` | `sendHttpData​(int rc, int options, String content_type, String data)` | Send HTTP data as a string with options.
    `void` | `sendHttpData​(int rc, String content_type, byte[] bytes)` | Send HTTP data.
    `void` | `sendHttpData​(int rc, String content_type, String data)` | Send HTTP data as a String.
    `void` | `setCommonName​(String certname)` | Set the common name of the connection.
    `void` | `setHttpHeader​(String name, String value)` | Set an HTTP header field for the following sendHttpData().
    `void` | `setIdentity​(String clientid, String user, String password)` | Set the identity of the connection.
    `void` | `setIdentity​(String clientid, String user, String password, int auth, boolean allowSteal)` | Set the identity of the connection and optionally start authenticate.
    `void` | `setKeepAlive​(int timeout)` | Sets the keep alive timeout for the connection.
    `void` | `setProtocol​(String protocol)` | Set the protocol for an incoming connection.
    `void` | `setUserData​(Object userData)` | Sets the user data associated with the connection.
    `String` | `simpleSubscriptionName()` | Create a simple subscription name for non-durable subscriptions.
    `void` | `suspendMessageDelivery()` | Temporarily suspend message deliver.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

    - #### Authenticated

          static final int Authenticated

      The connection is authenticated and authorized
      See Also:
        Constant Field Values

    - #### NotAuthenticated

          static final int NotAuthenticated

      The connection is not authorized and will be terminated
      See Also:
        Constant Field Values

    - #### ContinueAuthentication

          static final int ContinueAuthentication

      Continue authentication check with another module
      See Also:
        Constant Field Values

    - #### State_Handshake

          static final int State_Handshake

      The connection is in protocol handshake
      See Also:
        Constant Field Values

    - #### State_Accepted

          static final int State_Accepted

      The connection has been accepted but the not authenticated or authorized
      See Also:
        Constant Field Values

    - #### State_Authenticating

          static final int State_Authenticating

      The connection is in the process of being authenticated and authorized
      See Also:
        Constant Field Values

    - #### State_Open

          static final int State_Open

      The connection ia authorized and can process messages
      See Also:
        Constant Field Values

    - #### State_Closed

          static final int State_Closed

      The connection is closed
      See Also:
        Constant Field Values

    - #### HTTP_Option_Close

          static final int HTTP_Option_Close

      Close the connection after sending the response. This option s used to force the connection to be a single request/response or to force a close in the case of an error.
      See Also:
        Constant Field Values

    - #### HTTP_Option_ReadMsg

          static final int HTTP_Option_ReadMsg

      Increment the ReadMsg statistic for the connection and endpoint. This is used when the plug-in wishes to show that an incomming message is processed, even though it does not result in a message being sent from this connection.
      See Also:
        Constant Field Values

    - #### HTTP_Option_WriteMsg

          static final int HTTP_Option_WriteMsg

      Increment the WriteMsg stats for the connection and endpoint. This is used when the plug-in wishes to show that an outgoing message is processed, even though no message has been received on this connection.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### setProtocol

          void setProtocol​(String protocol)

      Set the protocol for an incoming connection. This action must be taken during an onProtocolCheck() callback in the plug-in listener.
      Parameters:
        `protocol` - The name of the protocol to accept.

    - #### setKeepAlive

          void setKeepAlive​(int timeout)

      Sets the keep alive timeout for the connection.

      If no data received on the connection during timeout period onLivenessCheck method of the ImaConnectionListener will be called.

      Parameters:
        `timeout` - The keep alive timeout in seconds

    - #### setIdentity

          void setIdentity​(String clientid,
                           String user,
                           String password)

      Set the identity of the connection.

      This sets the identity fields in the connection. This can be called during an onData() callback and will start authentication processing.

      Parameters:
        `clientid` - Set the clientID for the connection. Any connection which sends or receives messages must have a unique clientID.
        `user` - The name of the user which can be null.
        `password` - The password for the user which can be null

    - #### setIdentity

          void setIdentity​(String clientid,
                           String user,
                           String password,
                           int auth,
                           boolean allowSteal)

      Set the identity of the connection and optionally start authenticate.

      This sets the identity fields in the connection. This can be called during an onData() callback and will start authentication processing if the auth setting is ContinueAuthentication.

      * It can be called after receiving an onAuthenticate() on this connection and can be used to reset any identity fields changed by the authentication and to unblock processing on this connection.

      Parameters:
        `clientid` - Set the clientID for the connection. Any connection which sends or receives messages must have a unique clientID.
        `user` - The name of the user which can be null.
        `password` - The password for the user which can be null
        `auth` - The authentication setting
        `allowSteal` - If true, allow this session to steal the clientID of an existing connection

    - #### setCommonName

          void setCommonName​(String certname)

      Set the common name of the connection.

      This sets the common name in the connection. This can only be called before other authorization and is used for cases where the protocol determines the certificate name. When using transport certificates the existing common name should not be changed.

      Parameters:
        `certname` - The certificate common name

    - #### authenticate

          void authenticate​(int auth)

      Authenticate the connection.

      This can be called after receiving an onAuthenticate() and while the connection is blocked waiting for an authenticate. It authenticates without updating the identity information.

      If the auth setting is Authenticated, processing of the connection is unblocked and further processing is done using the existing identity. If the auth setting is NotAuthenticated, the connection is terminated. If the auth setting is ContinueAuthentication, the connection remains blocked and any other available authentication providers are tried.

      Parameters:
        `auth` - the authentication setting.

    - #### close

          void close()

      Close the connection normally.

    - #### close

          void close​(int rc,
                     String reason)

      Close the connection.
      Parameters:
        `rc` - The MessageSight return code for this close
        `reason` - A reason string associated with this close (this is logged)

    - #### log

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

      Put an entry into the log. This log entry is associated with this connection.
      Parameters:
        `msgid` - The message ID that can be any string. IBM MessageSight uses an alphabetic string followed by four digits.
        `level` - The level or severity of the log message (LOG_CRIT, LOG_ERROR, LOG_WARN, LOG_NOTICE, LOG_INFO)
        `category` - The category of the message. This is placed in the log. The categories "Connection", "Admin", and "Security" will cause the entry to go into the associated log. All other categories will appear in the default log.
        `msgformat` - The format of the message in Java MessageFormat string form
        `args` - A variable array of replacement values for the message format

    - #### getConnectionListener

          ImaConnectionListener getConnectionListener()

      Returns the connection listener associated with this connection. The connection listener is set at the time onConnection() is invoked on the plug-in listener and is null before onConnection() is called.
      Returns:
        The connection listener

    - #### getEndpoint

          ImaEndpoint getEndpoint()

      Returns the endpoint associated with this connection. The endpoint is a read-only object.
      Returns:
        The endpoint object or null to indicate there is no endpoint.

    - #### getIndex

          int getIndex()

      Returns the index associated with this connection.
      Returns:
        The index of a connection is used internally in the server and is made available here to allow correlation with problem determination of the server.

    - #### getProtocol

          String getProtocol()

      Returns the protocol associated with this connection.
      Returns:
        the name of the protocol or a zero length string to indicate the protocol is not set.

    - #### getProtocolFamily

          String getProtocolFamily()

      Returns the protocol family associated with this connection.
      Returns:
        the name of the protocol family or a zero length string to indicate the protocol is not set.

    - #### getCertName

          String getCertName()

      Returns the certificate name.
      Returns:
        the certificate name.

    - #### getClientAddress

          String getClientAddress()

      Returns the client IP address associated with this connection. Note that this represents the address of what is the other end of the connection and might in fact be the server in the case where the connection is initiated from the plug-in. This string might be null.
      Returns:
        the IP address of the other end of the connection

    - #### getClientID

          String getClientID()

      Returns the client ID.
      Returns:
        the client ID.

    - #### getClientPort

          int getClientPort()

      Returns the client port number associated with this connection. Note that this represents the port of the other end of the connection and might in fact be the server in the case where we initiate the connection. This string might be null.
      Returns:
        the port of the other end of the connection

    - #### getPassword

          String getPassword()

      Returns the password in obfuscated form.
      Returns:
        The obfuscated password

    - #### getState

          int getState()

      Returns the state of the connection.
      Returns:
        the state of the connection as a State_ constant from this class.

    - #### getUser

          String getUser()

      Returns the user name.
      Returns:
        the user name of null if there is no user name.

    - #### isClient

          boolean isClient()

      Returns whether this is an outgoing connection.
      Returns:
        true if the plug-in originated the connection, and false otherwise

    - #### isInternal

          boolean isInternal()

      Returns whether the connection is internal.
      Returns:
        true if the connection was created from the plug-in.

    - #### isReliable

          boolean isReliable()

      Returns whether the connection is reliable.
      Returns:
        true if this is a reliable connection such as TCP, false if it is an unreliable connection such as UDP.

    - #### isSecure

          boolean isSecure()

      Returns whether the connection is secure.
      Returns:
        true if this is a secure connection (SSL/TLS), false otherwise.

    - #### simpleSubscriptionName

          String simpleSubscriptionName()

      Create a simple subscription name for non-durable subscriptions. Durable subscriptions require a name which is the same when the consumer is connected to the subscription. Therefore this generated subscription name must not be used for durable subscriptions.
      Returns:
        A name which can be used as a unique name for a non-durable subscription.

    - #### newSubscription

          ImaSubscription newSubscription​(String topic)

      Create a new simple subscription object. Create a non-durable subscription to a topic destination. The subscription name is constructed.
      Parameters:
        `topic` - The topic name
      Returns:
        A subscription object which you can then subscribe to

    - #### newSubscription

          ImaSubscription newSubscription​(ImaDestinationType desttype,
                                          String dest,
                                          String name,
                                          ImaSubscriptionType subType,
                                          boolean nolocal,
                                          boolean transacted)

      Create a new subscription object. A subscription can be durable, but a subscription
      Parameters:
        `desttype` - The destination type (topic or queue)
        `dest` - The topic or queue name
        `name` - The subscription name
        `subType` - The subscription type (only for topics)
        `nolocal` - Whether local messages should be received.
      Returns:
        A subscription object which you can then subscribe to

    - #### getRetainedMessage

          void getRetainedMessage​(String topic,
                                  Object correlate)

      Receive the retained message (if any) from a topic. This call is asynchronous.
      Parameters:
        `topic` - The name of the topic
        `correlate` - the correlation object.
      Throws:
        `ImaPluginException` - if an error occurs while recquesting the retained message.

    - #### deleteRetained

          void deleteRetained​(String topic)

      Delete the retained message (if any) from a topic. No indication is returned about whether any retained message was actually deleted. Note that deleting like sending a retained message is a race between multiple publishers and the last one to be processed wins.
      Parameters:
        `topic` - The name of the topic

    - #### deleteRetained

          void deleteRetained​(String topic,
                              Object correlate)

      Delete the retained message (if any) from a topic. Delete the retained message and send a completion when done.
      Parameters:
        `topic` - The name of the topic
        `correlate` - The correlation object for onComplete.

    - #### requiredData

          void requiredData​(int needed)

      Specify the data required before the next onData call. Specify the number of bytes which should be in the data before the next onData() is called. This value is reset to zero on each call to onData(). This length includes any unused bytes from the onData() return value.

      This is used in cases such as protocols where the frame specifies a length. This allows the plug-in to indicate that data should be accumulated until a full frame is available before calling onData().

      Regardless of this setting, the onData callback should be prepared to handle the case where fewer than the needed number of bytes is specified by onData().

      Parameters:
        `needed` - The number of bytes required before re-invoking onData().

    - #### send

          void send​(ImaMessage message,
                    ImaDestinationType desttype,
                    String dest,
                    Object ackObj)

      Send a message to a destination. Between this call and the onComplete() callback for the message object, the message can be modified by the connection and should not be modified by the invoker.
      Parameters:
        `message` - The message to send
        `desttype` - The destination type (topic or queue)
        `dest` - The destination name
        `ackObj` - The object to send a complete on

    - #### publish

          void publish​(ImaMessage message,
                       String topic,
                       Object ackObj)

      Publish a message to a topic. This is the simplified from of send which only supports pub/sub Between this call and the onComplete() callback for the message object, the message can be modified by the connection and should not be modified by the invoker.
      Parameters:
        `message` - The message to publish
        `topic` - The topic name
        `ackObj` - The object to send a complete on

    - #### sendData

          void sendData​(String data)

      Send text output data on the connection. The data will be marked as text.
      Parameters:
        `data` - The string representing the data.

    - #### sendData

          void sendData​(byte[] data)

      Send binary output data on the connection as a byte array. The data will be marked as binary.
      Parameters:
        `data` - The data to send

    - #### sendData

          void sendData​(byte[] b,
                        int offset,
                        int len,
                        boolean isText)

      Send output data on the connection
      Parameters:
        `data` - The data to send
        `offset` - The starting offset in the data
        `len` - The length of data to send
        `isText` - If true the data represents text data in UTF-8 encoding.

    - #### destroySubscription

          void destroySubscription​(Object obj,
                                   String name,
                                   ImaSubscriptionType subType)

      Destroy a subscription. Destroy subscription is only required for durable subscriptions. Non-durable subscriptions are automatically destroyed when there are no more consumers.
      Parameters:
        `obj` - An object to return on completion
        `name` - The name of the subscription
        `subType` - The subscription type of the object
      Throws:
        `ImaPluginException` - if an error occurs while destroying a subscription.

    - #### sendHttpData

          void sendHttpData​(int rc,
                            String content_type,
                            byte[] bytes)

      Send HTTP data. This can only be done as a result of an onHttpData() call. Each onHttpData() call but result in one and only one sendHttpData(). All operations are assumed to allow content to be returned, but the return code of 204 (No content) will force the content to be null.

      For errors it is recommended that a description of the error be returned in "text/plain".

      If you return html text you must ensure that a less than sign or ampersand are not put in the stream unescaped

      The following return codes are allowed:

      200
        OK
      201
        Created
      202
        Accepted
      203
        Non-authoratative
      204
        No content (content_type and bytes are ignored for this return code)
      205
        Reset content
      400
        Bad request
      403
        Forbidden
      404
        Not found
      405
        Method not allowed
      406
        Not acceptable
      409
        Conflict
      410
        Gone
      413
        Request too large
      415
        Unsupported media type
      500
        Server error
      501
        Not implemented
      503
        Service Unavailable
      Parameters:
        `rc` - An HTTP return code.
        `content_type` - The content type of the result. If null, "text/plain" is used.
        `bytes` - The byte content of the result. If null value results in a zero length content.
      Throws:
        `IllegalArgumentException` - if an onHttpData is not active

    - #### sendHttpData

          void sendHttpData​(int rc,
                            int options,
                            String content_type,
                            byte[] bytes)

      Send HTTP data with options. This can only be done as a result of an onHttpData() call. Each onHttpData() call but result in one and only one sendHttpData(). All operations are assumed to allow content to be returned, but the return code of 204 (No content) will force the content to be null.

      The options allow special processing to be done as the result of sending this response.

      Parameters:
        `rc` - An HTTP return code.
        `options` - HTTP send options (HTTP_Option_*) which can be ORed together
        `content_type` - The content type of the result. If null the content type is determined by examination of the content.
        `bytes` - The byte content of the result/ A null value results in a zero length content.
      Throws:
        `IllegalArgumentException` - if an onHttpData is not active

    - #### sendHttpData

          void sendHttpData​(int rc,
                            String content_type,
                            String data)

      Send HTTP data as a String. This can only be done as a result of an onHttpData() call. Each onHttpData() call but result in one and only one sendHttpData().
      Parameters:
        `rc` - An HTTP return code. Only a restricted set of HTTP return codes are allowed
        `content_type` - The content type of the result. If null, "text/plain" is used.
        `bytes` - The byte content of the result. If null an empty string is used.
        `rc` - An HTTP return code.
        `content_type` - The content type of the result. If null the content type is determined by examination of the content.
        `data` - The string content of the result/ A null value results in a zero length content.
      Throws:
        `IllegalArgumentException` - if an onHttpData is not active
        `IllegalArgumentException` - if an onHttpData is not active

    - #### sendHttpData

          void sendHttpData​(int rc,
                            int options,
                            String content_type,
                            String data)

      Send HTTP data as a string with options. This can only be done as a result of an onHttpData() call. Each onHttpData() call but result in one and only one sendHttpData(). All operations are assumed to allow content to be returned, but the return code of 204 (No content) will force the content to be null.

      The options allow special processing to be done as the result of sending this response.

      Parameters:
        `rc` - An HTTP return code.
        `options` - HTTP send options (HTTP_Option_*) which can be ORed together
        `content_type` - The content type of the result. If null the content type is determined by examination of the content.
        `data` - The string content of the result. If null an empty string is used.
      Throws:
        `IllegalArgumentException` - if an onHttpData is not active

    - #### getHttpCookie

          String getHttpCookie​(String name)

      Get an HTTP cookie by name.
      Parameters:
        `name` - The name of the cookie
      Returns:
        The value of the coolie or null if the cookie is not set

    - #### getHttpCookieSet

          Set<String> getHttpCookieSet()

      Get a Set of HTTP cookie names.
      Returns:
        A set of the names of cookies from the current HTTP connection or null if there are none.

    - #### getHttpHeader

          String getHttpHeader​(String name)

      Get an HTTP header from the current HTTP connection. Only those headers defines in the HttpHeader property of the protocol definition are available.
      Parameters:
        `name` - The name of the header
      Returns:
        The value of the header or null if the header is not set

    - #### setHttpHeader

          void setHttpHeader​(String name,
                             String value)

      Set an HTTP header field for the following sendHttpData().

      This header is sent as a custom header file in the HTTP response.

      Parameters:
        `name` - The name of the header
        `value` - The value of the header
      Throws:
        `IllegalArgumentException` - if an onHttpData is not active

    - #### getUserData

          Object getUserData()

      Returns the user data associated with the connection.

      Normally the ImaConnectionListener object returned from ImaPluginListener.onConnection defines the object associated with the connection, but this method returns another object which is attached to the connection.

      Returns:
        user data object

    - #### setUserData

          void setUserData​(Object userData)

      Sets the user data associated with the connection.

      Normally the ImaConnectionListener object returned from ImaPluginListener.onConnection defines the object associated with the connection, but this method allows another object to be attached to the connection.

    - #### suspendMessageDelivery

          void suspendMessageDelivery()

      Temporarily suspend message deliver.

      This method is used to create a flow control and stop the delivery of messages to a connection so the the consumer can catch up. The method resumeMessgeDelivery() should be called when the receiver is ready to accept messages.

    - #### resumeMessageDelivery

          void resumeMessageDelivery()

      Resume message deliver.

      This method is used to create a flow control and resume the delivery of messages to a connection so the the consumer can catch up.

    - #### createTransaction

          void createTransaction​(ImaTransactionListener listener)

      Create a transaction

      A transaction allows a set of messages to be sent as an atomic set.

      Parameters:
        `listener` -