Class SMQ
- Direct Known Subclasses:
AndroidSMQ
,SwingSMQ
Each SMQ instance creates two threads, where one thread is used for
upstream data and the other thread is used for downstream data. All
user callbacks run in the context of the downstream thread. The
callback action should be delegated in non thread safe UI code such
as Swing and Android. See the utility classes SwingSMQ
and
AndroidSMQ
for more information.
The SMQ instance will not garbage collect unless method
close(boolean, RTL.SMQ.IntfOnClose)
is called, which terminates the two threads.
All methods sending messages to the broker (such as publish) return immediately and before the message is sent to the broker. The message being sent is queued internally and sent one at a time by the upstream thread running in the background.
- See Also:
-
Constructor Summary
ConstructorDescriptionSMQ
(URL smqUrl, TrustManager[] trustMgr, HostnameVerifier hostVerifier, Proxy proxy, IntfOnClose onClose) Create an SMQ client instance -
Method Summary
Modifier and TypeMethodDescriptionvoid
close
(boolean flush, IntfOnClose onClose) Terminate the upstream and downstream threads and close the broker connection if the connection is established.void
Connect to the broker and morph (upgrade) the HTTPS connection to a persistent and secure (encrypted) TCP connection.boolean
Returns true if the client is connected.void
create
(String topic, String subtopic, IntfOnCreateAck ack) Create a topic name and sub topic name.void
create
(String topic, IntfOnCreateAck ack) Create a topic and fetch the topic ID (tid).void
createsub
(String subtopic, IntfOnCreatsubeAck ack) final long
getETid()
Returns the client's ephemeral topic ID.final String
Returns the client's IP address as seen by the server.final long
getRand()
Returns the random number provided by the broker.void
init()
The init method initiates a connection with the broker.void
observe
(long tid, IntfOnChange ch) Requests the broker to provide change notification events when the number of subscribers to a specific topic changes.void
observe
(String topic, IntfOnChange ch) Requests the broker to provide change notification events when the number of subscribers to a specific topic changes.void
publish
(long tid, long subtid, byte[] data) Publish a message to a (named topic or ephemeral topic ID) and to a named subtopic.void
publish
(long tid, long subtid, byte[] b, int off, int len) Publish a message to a (named topic or ephemeral topic ID) and to a named subtopic.void
Publish a message to a named topic and set subtopic ID to zero.void
Publish a message to a named topic and subtopic.void
Publish a message to a named topic and set subtopic ID to zero.void
Publish a message to a named topic and subtopic.void
Publish a message to a named topic and subtopic.void
subscribe
(String topic, String subtopic, IntfOnMsg msg, IntfOnCreateAck ack) Subscribe to a named topic and to a named subtopic.void
subscribe
(String topic, IntfOnMsg msg, IntfOnCreateAck ack) Subscribe to a named topic, but no subtopic and create a "catch all" for subtopics not subscribed to (including zero for no subtopic).long
subtopic2tid
(String subtopic) Translates a subtopic name known to the client to subtopic ID.tid2subtopic
(long subtid) Translates subtopic ID known to the client to subtopic name.tid2topic
(long tid) Translates topic ID known to the client to topic name.long
Translates a topic name known to the client to topic ID (tid).void
unobserve
(long tid) Stop receiving change notifications for a named topic or ephemeral topic ID.void
Stop receiving change notifications for a named topic.void
unsubscribe
(long tid) Requests the server to unsubscribe the client from a topic.void
unsubscribe
(String topic) Requests the server to unsubscribe the client from a topic.
-
Constructor Details
-
SMQ
public SMQ(URL smqUrl, TrustManager[] trustMgr, HostnameVerifier hostVerifier, Proxy proxy, IntfOnClose onClose) Create an SMQ client instance- Parameters:
smqUrl
- The broker URL must be an HTTPS type URL. An exception is thrown for non secure HTTP URLs.trustMgr
- Optional TrustManager. The default TrustManager is used if this parameter is null. The utility classTrustAny
provides a TrustManager that accepts any certificate, including self signed certificates.hostVerifier
- Optional HostnameVerifier. The default HostnameVerifier is used if this parameter is null. The utility classTrustAny
provides a HostnameVerifier that accepts any domain/hostname.proxy
- Optional Proxy. The system default proxy (or none) is used if this parameter is null.onClose
- The client calls the user proved callback if the broker gracefully closed the connection, or if the connection unexpectedly closed.- See Also:
-
-
Method Details
-
getRand
public final long getRand()Returns the random number provided by the broker. The method can be called as soon asinit()
returns. -
getIpAddr
Returns the client's IP address as seen by the server. This address may not be the same as the client's IP address if the client is behind a NAT router. The client's IP address can be used by hash based authentication to further strengthen the hash value. The method can be called as soon asinit()
returns. -
getETid
public final long getETid()Returns the client's ephemeral topic ID. -
init
The init method initiates a connection with the broker. The init method can optionally be called prior to callingconnect(byte[], java.lang.String, java.lang.String)
if data available from the following methods are required by the code calling connect:getRand()
andgetIpAddr()
.- Throws:
SmqException
-
connect
Connect to the broker and morph (upgrade) the HTTPS connection to a persistent and secure (encrypted) TCP connection. Methodinit()
is called by connect unless init was explicitly called prior to calling connect.- Parameters:
credentials
- must be provided if the broker requires password based authentication and should be set to null if no authentication is required. See the SMQ JavaScript client for suggestions on how to manage authentication.info
- an optional string that may be used by server side code interacting with the broker.- Throws:
SmqException
-
connected
public boolean connected()Returns true if the client is connected. -
topic2tid
Translates a topic name known to the client to topic ID (tid).- Parameters:
topic
- topic name- Returns:
- a non zero value if the topic is known to the client and zero if the topic is not known.
- See Also:
-
subtopic2tid
Translates a subtopic name known to the client to subtopic ID.- Parameters:
subtopic
- name- Returns:
- a non zero value if the subtopic is known to the client and zero if the topic is not known.
- See Also:
-
tid2topic
Translates topic ID known to the client to topic name.- Parameters:
tid
- topic ID- Returns:
- a string if the topic name is known to the client and null if the topic is not known.
- See Also:
-
tid2subtopic
Translates subtopic ID known to the client to subtopic name.- Parameters:
subtid
- subtopic ID- Returns:
- a string if the subtopic name is known to the client and null if the subtopic is not known.
- See Also:
-
create
Create a topic and fetch the topic ID (tid). The SMQ protocol is optimized and does not directly use a string when publishing, but a number. The server randomly creates a 32 bit number and persistently stores the topic name and number. The 'create' method is typically used prior to publishing a message on a specific topic if the server logic implements authorization. Otherwise, the publish method can be used directly with a topic string since the publish method takes care of first creating a topic if you publish to a topic unknown to the client stack.The create method is used internally by the publish methods (using topic name) if the topic is not known to the client when publish is called.
- Parameters:
topic
- the topic name where you plan on publishing messages.ack
- the on response callback.- Throws:
SmqException
-
create
Create a topic name and sub topic name.- Parameters:
topic
- the topic name where you plan on publishing messages.subtopic
- the secondary topic name.ack
- the on response callback.- Throws:
SmqException
- See Also:
-
createsub
- Parameters:
subtopic
-ack
- the on response callback- Throws:
SmqException
-
subscribe
public void subscribe(String topic, String subtopic, IntfOnMsg msg, IntfOnCreateAck ack) throws SmqException Subscribe to a named topic and to a named subtopic. You can subscribe multiple times to the same topic for different subtopic names.The topic name "self" is interpreted as subscribing to the client's own Ephemeral Topic ID (etid) -- in other words, it means subscribing to the (tid) returned by method
getETid()
. Subscribing to your own Ephemeral Topic ID makes it possible for other connected clients to send a message directly to this client.- Parameters:
topic
- the topic name to subscribe to. The topic name 'self' means subscribing to the client's own Ephemeral Topic ID.subtopic
- the subtopic name to subscribe to.msg
- the message callback is called for each message received from the broker.ack
- optional on subscribe ack callback. Set to null if not needed.- Throws:
SmqException
-
subscribe
Subscribe to a named topic, but no subtopic and create a "catch all" for subtopics not subscribed to (including zero for no subtopic).The topic name "self" is interpreted as subscribing to the client's own Ephemeral Topic ID (etid) -- in other words, it means subscribing to the (tid) returned by method
getETid()
. Subscribing to your own Ephemeral Topic ID makes it possible for other connected clients to send a message directly to this client.- Parameters:
topic
- the topic name to subscribe to. The topic name 'self' means subscribing to the client's own Ephemeral Topic ID.msg
- the message callback is called for each message received from the broker.ack
- optional on subscribe ack callback. Set to null if not needed.- Throws:
SmqException
-
publish
Publish a message to a named topic and set subtopic ID to zero.- Parameters:
topic
- the topic name is automatically translated to topic ID if the topic name is not known by the client.data
- the data to published.- Throws:
SmqException
-
publish
Publish a message to a named topic and set subtopic ID to zero.- Parameters:
topic
- the topic name is automatically translated to topic ID if the topic name is not known by the client.msg
- the string to be published is converted to a UTF-8 data array.- Throws:
SmqException
- See Also:
-
publish
Publish a message to a named topic and subtopic.- Parameters:
topic
- the topic name is automatically translated to topic ID if the topic name is not known by the client.subtopic
- the subtopic name is automatically translated to subtopic ID if the subtopic name is not known by the client.msg
- the string to be publish is converted to a UTF-8 data array- Throws:
SmqException
- See Also:
-
publish
Publish a message to a named topic and subtopic.- Parameters:
topic
- the topic name is automatically translated to topic ID if the topic name is not known by the client.subtopic
- the subtopic name is automatically translated to subtopic ID if the subtopic name is not known by the client.data
- the data to publish.- Throws:
SmqException
-
publish
Publish a message to a named topic and subtopic.- Parameters:
topic
- the topic name is automatically translated to topic ID if the topic name is not known by the client.subtid
- the subtopic ID (from named subtopic). Set to zero if not used.data
- the data to publish.- Throws:
SmqException
-
publish
Publish a message to a (named topic or ephemeral topic ID) and to a named subtopic.- Parameters:
tid
- the topic ID (from named topic) or ephemeral topic ID.subtid
- the subtopic ID (from named subtopic). Set to zero if not used.data
- the data to publish.- Throws:
SmqException
-
publish
Publish a message to a (named topic or ephemeral topic ID) and to a named subtopic.- Parameters:
tid
- the topic ID (from named topic) or ephemeral topic ID.subtid
- the subtopic ID (from named subtopic). Set to zero if not used.b
- the data to published.off
- the start offset in the data.len
- the number of bytes to write.- Throws:
SmqException
-
unsubscribe
Requests the server to unsubscribe the client from a topic. All registered callback interfaces, including all callbacks for subtopics, will be removed from the client stack.- Parameters:
topic
- name- Throws:
SmqException
-
unsubscribe
Requests the server to unsubscribe the client from a topic. All registered callback interfaces, including all callbacks for subtopics, will be removed from the client stack.- Parameters:
tid
- the topic ID (from named topic).- Throws:
SmqException
-
observe
Requests the broker to provide change notification events when the number of subscribers to a specific topic changes.- Parameters:
topic
- namech
- the callback called when the number of subscribers changes.- Throws:
SmqException
-
observe
Requests the broker to provide change notification events when the number of subscribers to a specific topic changes. Ephemeral topic IDs can also be observed. The number of connected subscribers for an ephemeral ID can only be one, which means the client is connected. Receiving a change notification for an ephemeral ID means the client has disconnected and that you no longer will get any change notifications for the observed topic ID. The client stack automatically "unobserves" observed ephemeral topic IDs when it receives a change notification.- Parameters:
tid
- the topic ID (from named topic) or ephemeral topic ID.ch
- the callback called when the number of subscribers changes.- Throws:
SmqException
-
unobserve
Stop receiving change notifications for a named topic.- Parameters:
topic
- name- Throws:
SmqException
-
unobserve
Stop receiving change notifications for a named topic or ephemeral topic ID.- Parameters:
tid
- the topic ID (from named topic) or ephemeral topic ID.- Throws:
SmqException
-
close
Terminate the upstream and downstream threads and close the broker connection if the connection is established. The SMQ object can no longer be used after calling the close method.- Parameters:
flush
- send all pending outstream messages prior to closing the connection.onClose
- optional callback
-