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 authorizedstatic int
ContinueAuthentication
Continue authentication check with another modulestatic 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 terminatedstatic int
State_Accepted
The connection has been accepted but the not authenticated or authorizedstatic int
State_Authenticating
The connection is in the process of being authenticated and authorizedstatic int
State_Closed
The connection is closedstatic int
State_Handshake
The connection is in protocol handshakestatic 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 transactionvoid
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 connectionvoid
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 nullauth
- The authentication settingallowSteal
- 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 closereason
- 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 formargs
- 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 namename
- The subscription namesubType
- 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 topiccorrelate
- 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 topiccorrelate
- 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 senddesttype
- The destination type (topic or queue)dest
- The destination nameackObj
- 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 publishtopic
- The topic nameackObj
- 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 sendoffset
- The starting offset in the datalen
- The length of data to sendisText
- 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 completionname
- The name of the subscriptionsubType
- 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 togethercontent_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 allowedcontent_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 activeIllegalArgumentException
- 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 togethercontent_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 headervalue
- 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 transactionA transaction allows a set of messages to be sent as an atomic set.
- Parameters:
listener
-
-
-