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 timestamp of the request
- the number of items in the client queue
Topic listeners
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.