Package RTL.SMQ

Class SMQ

java.lang.Object
RTL.SMQ.SMQ
Direct Known Subclasses:
AndroidSMQ, SwingSMQ
public class SMQ extends Object
The Simple Message Queue (SMQ) Java client provides a similar high level API as the JavaScript SMQ client. However, the use of the API differs in that the Java methods for publish, subscribe, etc. cannot be used when the client is not connected. An exception is thrown if you attempt to publish or subscribe if the client is not connected to a broker.

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

    Constructors
    Constructor
    Description
    SMQ(URL smqUrl, TrustManager[] trustMgr, HostnameVerifier hostVerifier, Proxy proxy, IntfOnClose onClose)
    Create an SMQ client instance

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close(boolean flush, IntfOnClose onClose)
    Terminate the upstream and downstream threads and close the broker connection if the connection is established.
    void
    connect(byte[] uid, String credentials, String info)
    Connect to the broker and morph (upgrade) the HTTPS connection to a persistent and secure (encrypted) TCP connection.
    boolean
    connected()
    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
    getIpAddr()
    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(String topic, byte[] data)
    Publish a message to a named topic and set subtopic ID to zero.
    void
    publish(String topic, long subtid, byte[] data)
    Publish a message to a named topic and subtopic.
    void
    publish(String topic, String msg)
    Publish a message to a named topic and set subtopic ID to zero.
    void
    publish(String topic, String subtopic, byte[] data)
    Publish a message to a named topic and subtopic.
    void
    publish(String topic, String subtopic, String msg)
    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.
    String
    tid2subtopic(long subtid)
    Translates subtopic ID known to the client to subtopic name.
    String
    tid2topic(long tid)
    Translates topic ID known to the client to topic name.
    long
    topic2tid(String topic)
    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
    unobserve(String topic)
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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 class TrustAny 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 class TrustAny 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 as init() returns.

    • getIpAddr

      public final String 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 as init() returns.

    • getETid

      public final long getETid()
      Returns the client's ephemeral topic ID.

    • init

      public void init() throws SmqException
      The init method initiates a connection with the broker. The init method can optionally be called prior to calling connect(byte[], java.lang.String, java.lang.String) if data available from the following methods are required by the code calling connect: getRand() and getIpAddr().
      Throws:
      SmqException

    • connect

      public void connect(byte[] uid, String credentials, String info) throws SmqException
      Connect to the broker and morph (upgrade) the HTTPS connection to a persistent and secure (encrypted) TCP connection. Method init() 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

      public long topic2tid(String topic)
      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

      public long subtopic2tid(String subtopic)
      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

      public String tid2topic(long tid)
      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

      public String tid2subtopic(long subtid)
      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

      public void create(String topic, IntfOnCreateAck ack) throws SmqException
      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

      public void create(String topic, String subtopic, IntfOnCreateAck ack) throws SmqException
      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

      public void createsub(String subtopic, IntfOnCreatsubeAck ack) throws SmqException
      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

      public void subscribe(String topic, IntfOnMsg msg, IntfOnCreateAck ack) throws SmqException
      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

      public void publish(String topic, byte[] data) throws SmqException
      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

      public void publish(String topic, String msg) throws SmqException
      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

      public void publish(String topic, String subtopic, String msg) throws SmqException
      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

      public void publish(String topic, String subtopic, byte[] data) throws SmqException
      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

      public void publish(String topic, long subtid, byte[] data) throws SmqException
      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

      public void publish(long tid, long subtid, byte[] data) throws SmqException
      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

      public void publish(long tid, long subtid, byte[] b, int off, int len) throws SmqException
      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

      public void unsubscribe(String topic) throws SmqException
      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

      public void unsubscribe(long tid) throws SmqException
      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

      public void observe(String topic, IntfOnChange ch) throws SmqException
      Requests the broker to provide change notification events when the number of subscribers to a specific topic changes.
      Parameters:
      topic - name
      ch - the callback called when the number of subscribers changes.
      Throws:
      SmqException

    • observe

      public void observe(long tid, IntfOnChange ch) throws SmqException
      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

      public void unobserve(String topic) throws SmqException
      Stop receiving change notifications for a named topic.
      Parameters:
      topic - name
      Throws:
      SmqException

    • unobserve

      public void unobserve(long tid) throws SmqException
      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

      public void close(boolean flush, IntfOnClose onClose)
      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