Table of Contents
Just a second...

Using the Android Classic API

There are features, issues, and considerations that are specific to clients that are implemented using the Android™ Classic API.

Credentials

When credentials are required, there are three ways to set the credentials. The ServerDetails, the ConnectionDetails and the DiffusionClient all have a setCredentials method. It is required that the user create a DiffusionCredentials object and pass it to one of these methods before calling connect. Use only one of these ways. If more than one way is used, the selection of the credentials to use is undefined. The Android Classic API only supports sending credentials on connection.

onMessage event

When messages arrive from the Diffusion™ server on a subscribed topic, the onMessage is called on the delegate provided. The message is wrapped in a interface called Message. This interface contains helper methods that surround the message itself, like getTopic() and isInitialTopicLoad. For more information, see Android Unified API documentation.

Subscriptions

Once the client has connected, you can issue subscribe and unsubscribe commands. The subscribe and unsubscribe methods take a string format, that can be a topic selector pattern, a list of topics that are comma delimited, or a single topic.

Send

Once connected a client can send messages to the Diffusion server on a particular topic. To do this, use the send method.

theClient.send("Fred","Hello Fred");

In the example above, the registered message handler of the topic Fred receives a messageFromClient notification. If the message requires a user header, use the sendTopicMessage method. A TopicMessage allows for the setting of user headers.

    TopicMessage message = new TopicMessage("Fred");
    message.addUserHeader("myHeaders");
    message.setMessage("Hello Fred");
    theClient.sendTopicMessage(message);

Ping

The client can ping the Diffusion server. The delegate is notified of the response by the onPing function. The resulting ping event has two attributes in it:
  • the timestamp of the request
  • the number of items in the client queue
This information enables the client to get some vital connection information. It is down to the implementation of the client to specify the ping frequency, if at all required.

Topic listeners

During the life time of the connection, it might be required to have modular components that get notified about topic messages, these are topic listeners. A topic listener is called using its onMessage method with a message object when the topic of the message matches the topic name.
Note: For performance the Android topic listeners do not have regular expression patterns but topic name matching.
You can have many topic listeners on the same topic path if required. For example, if you want to be notified about a particular topic, use the following code:
	theClient.addTopicListener(topicListener);

Where topicListener implements the interface TopicListener. See the following example.

    /**
     * getTopic
     * 
     * @return the topic that this listener is interested in. This does
     * not take regular expressions this must be an exact match
     */
    String getTopic();
 
    /**
     * onMessage
     * 
     * @param message message which topic matches the getTopic method
     */
    void onMessage(Message message);

Remove topic listeners by calling the removeTopicListener method on the DiffusionClient class.

Threading concerns

The DiffusionClient creates and dedicates a thread to listening to traffic from the Diffusion server and reacting to messages from it. Consequently methods on the DiffusionConnectionListener and DiffusionTopicStatusListener are executed in the same thread. Android does not allow background threads to interact with GUI controls, only the main thread is allowed to do so.

To overcome this, any non-main thread can pass a java.lang.Runnable to the main thread for execution via android.view.View.post(Runnable action). For example:

/*
 * Called when the Diffusion connection is established
 */
public void connected() {
    // Post this Runnable to the GUI thread to change the display
   	String statusTextStr = String.format( "Connected to %s:%d\n", HOST, PORT );
   	setStatus( statusTextStr );
   	Log.i( TAG, statusTextStr );
  }
    
   /**
    * Set the content of the status view
    * @param statusStr
    */
   private void setStatus(final String statusStr) 
    {
// Pass a Runnable to the GUI thread to execute using one of its widgets
     outputView.post( new Runnable() {
         public void run() {
            statusText.setText( statusStr );
        }
     } );
 }

User permissions in Manifest.xml

To establish a connection with the Diffusion server, Android devices must add the user permission INTERNET within the Manifest.xml. This permission allows applications to open network sockets.