public interface ImaConnection
Modifier and Type | Field and 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
|
Modifier and Type | Method and 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.
|
static final String COPYRIGHT
static final int Authenticated
static final int NotAuthenticated
static final int ContinueAuthentication
static final int State_Handshake
static final int State_Accepted
static final int State_Authenticating
static final int State_Open
static final int State_Closed
static final int HTTP_Option_Close
static final int HTTP_Option_ReadMsg
static final int HTTP_Option_WriteMsg
void setProtocol(String protocol)
protocol
- The name of the protocol to accept.void setKeepAlive(int timeout)
If no data received on the connection during timeout period onLivenessCheck method of the ImaConnectionListener will be called.
timeout
- The keep alive timeout in secondsvoid setIdentity(String clientid, String user, String password)
This sets the identity fields in the connection. This can be called during an onData() callback and will start authentication processing.
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 nullvoid setIdentity(String clientid, String user, String password, int auth, boolean allowSteal)
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.
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 connectionvoid setCommonName(String certname)
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.
certname
- The certificate common namevoid authenticate(int auth)
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.
auth
- the authentication setting.void close()
void close(int rc, String reason)
rc
- The MessageSight return code for this closereason
- A reason string associated with this close (this is logged)void log(String msgid, int level, String category, String msgformat, Object... args)
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 formatImaConnectionListener getConnectionListener()
ImaEndpoint getEndpoint()
int getIndex()
String getProtocol()
String getProtocolFamily()
String getCertName()
String getClientAddress()
String getClientID()
int getClientPort()
String getPassword()
int getState()
String getUser()
boolean isClient()
boolean isInternal()
boolean isReliable()
boolean isSecure()
String simpleSubscriptionName()
ImaSubscription newSubscription(String topic)
topic
- The topic nameImaSubscription newSubscription(ImaDestinationType desttype, String dest, String name, ImaSubscriptionType subType, boolean nolocal, boolean transacted)
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.void getRetainedMessage(String topic, Object correlate)
topic
- The name of the topiccorrelate
- the correlation object.ImaPluginException
- if an error occurs while recquesting the retained message.void deleteRetained(String topic)
topic
- The name of the topicvoid deleteRetained(String topic, Object correlate)
topic
- The name of the topiccorrelate
- The correlation object for onComplete.void requiredData(int needed)
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().
needed
- The number of bytes required before re-invoking onData().void send(ImaMessage message, ImaDestinationType desttype, String dest, Object ackObj)
message
- The message to senddesttype
- The destination type (topic or queue)dest
- The destination nameackObj
- The object to send a complete onvoid publish(ImaMessage message, String topic, Object ackObj)
message
- The message to publishtopic
- The topic nameackObj
- The object to send a complete onvoid sendData(String data)
data
- The string representing the data.void sendData(byte[] data)
data
- The data to sendvoid sendData(byte[] b, int offset, int len, boolean isText)
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.void destroySubscription(Object obj, String name, ImaSubscriptionType subType)
obj
- An object to return on completionname
- The name of the subscriptionsubType
- The subscription type of the objectImaPluginException
- if an error occurs while destroying a subscription.void sendHttpData(int rc, String content_type, byte[] bytes)
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:
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.IllegalArgumentException
- if an onHttpData is not activevoid sendHttpData(int rc, int options, String content_type, byte[] bytes)
The options allow special processing to be done as the result of sending this response.
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.IllegalArgumentException
- if an onHttpData is not activevoid sendHttpData(int rc, String content_type, String data)
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.IllegalArgumentException
- if an onHttpData is not activeIllegalArgumentException
- if an onHttpData is not activevoid sendHttpData(int rc, int options, String content_type, String data)
The options allow special processing to be done as the result of sending this response.
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.IllegalArgumentException
- if an onHttpData is not activeString getHttpCookie(String name)
name
- The name of the cookieSet<String> getHttpCookieSet()
String getHttpHeader(String name)
name
- The name of the headervoid setHttpHeader(String name, String value)
This header is sent as a custom header file in the HTTP response.
name
- The name of the headervalue
- The value of the headerIllegalArgumentException
- if an onHttpData is not activeObject getUserData()
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.
void setUserData(Object userData)
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.
void suspendMessageDelivery()
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.
void resumeMessageDelivery()
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.
void createTransaction(ImaTransactionListener listener)
A transaction allows a set of messages to be sent as an atomic set.
listener
- Copyright © Contributors to the Eclipse Foundation 2014-2021