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

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