View source for Android Remote Bound Services – A Worked Example

<table border="0" cellspacing="0">
<tr>
<td width="20%">[[Android Local Bound Services – A Worked Example|Previous]]<td align="center">[[Android 4 App Development Essentials|Table of Contents]]<td width="20%" align="right">[[An Overview of Android SQLite Databases|Next]]</td>
<tr>
<td width="20%">Android Local Bound Services – A Worked Example<td align="center"><td width="20%" align="right">An Overview of Android SQLite Databases</td>
</table>
<hr>


<htmlet>android44</htmlet>


In this, the final chapter dedicated to Android services, an example application will be developed to demonstrate the use of a messenger and handler configuration to facilitate interaction between a client and remote bound service.

== Client to Remote Service Communication ==

As outlined in the previous chapter, interaction between a client and a local service can be implemented by returning to the client an IBinder object containing a reference to the service object. In the case of remote services, however, this approach does not work because the remote service is running in a different process and, as such, cannot be reached directly from the client.

In the case of remote services, a Messenger and Handler configuration must be created that allows messages to be passed across process boundaries between client and service.

Specifically, the service creates a Handler instance that will be called when a message is received from the client. In terms of initialization, it is the job of the Handler to create a Messenger object which, in turn, creates an IBinder object to be returned to the client in the onBind() method. This IBinder object is used by the client to create an instance of the Messenger object and, subsequently, to send messages to the service handler. Each time a message is sent by the client, the handleMessage() method of the handler is called, passing through the message object.

The simple example created in this chapter will consist of an activity and a bound service running in separate processes. The Messenger/Handler mechanism will be used to send a string to the service, which will then display that string in a Toast message.

==  Creating the Example Application ==

Launch Eclipse and create a new Android project named RemoteBound with a package name of com.example.remotebound, default icons and a blank activity named RemoteBoundActivity with a corresponding layout file named activity_remote_bound and a fragment file named fragment_remote_bound.

== Designing the User Interface ==

Locate the fragment_remote_bound.xml file in the Package Explorer panel and double click on it to load it into the Graphical Layout tool. Right-click on the TextView object currently in the layout, select the Change Widget Type menu option and change the widget to a Button view. Change the text on the button to read “Send Message” by right-clicking, selecting the Edit Text… menu option and creating a new string resource named button_text. Finally, drag the button and position it in the center of the display canvas

Next, switch to the XML view and modify the Button view element to declare an onClick property for the button:

<pre>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:paddingBottom="@dimen/activity_vertical_margin"
    android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    tools:context=".RemoteBoundActivity" >

    <Button
        android:id="@+id/Button1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_centerHorizontal="true"
        android:layout_centerVertical="true"
        android:onClick="sendMessage"
        android:text="@string/button_text" />

</RelativeLayout>
</pre>

Once the changes have been made to the XML, be sure to save the file before proceeding.

== Implementing the Remote Bound Service ==

In order to implement the remote bound service for this example, add a new class to the project by right-clicking on the RemoteBound project name in the Package Explorer panel and selecting the New -> Class menu option. Create a new class named RemoteService, subclassed from android.app.Service and allocated to the current application package.

The first step is to implement the handler class for the service. This is achieved by extending the Handler class and implementing the handleMessage() method. This method will be called when a message is received from the client. It will be passed as an argument a Message object containing any data that the client needs to pass to the service. In this instance, this will be a Bundle object containing a string to be displayed to the user. The modified class in the RemoteService.java file should read as follows once this has been implemented:

<pre>
package com.example.remotebound;

import android.app.Service;
import android.content.Intent;
import android.os.Bundle;
import android.os.Handler;
import android.os.IBinder;
import android.os.Message;
import android.widget.Toast;
import android.os.Messenger;

public class RemoteService extends Service {

	class IncomingHandler extends Handler {
        @Override
        public void handleMessage(Message msg) {
            
        	Bundle data = msg.getData();        	
        	String dataString = data.getString("MyString");
        	Toast.makeText(getApplicationContext(), 
                     dataString, Toast.LENGTH_SHORT).show();
        }
     }
	
	@Override
	public IBinder onBind(Intent intent) {
		// TODO Auto-generated method stub
		return null;
	}

}
</pre>

With the handler implemented, the only remaining task in terms of the service code is to modify the onBind() method such that it returns an IBinder object containing a Messenger object which, in turn, contains a reference to the handler:

<pre>
final Messenger myMessenger = new Messenger(new IncomingHandler());
	
@Override
public IBinder onBind(Intent intent) {
      return myMessenger.getBinder();
}
</pre>

The first line of the above code fragment creates a new instance of our handler class and passes it through to the constructor of a new Messenger object. Within the onBind() method, the getBinder() method of the messenger object is called to return the messenger’s IBinder object.

== Configuring a Remote Service in the Manifest File ==

In order to portray the communication between a client and remote service accurately, it will be necessary to configure the service to run in a separate process from the rest of the application. This is achieved by adding an android:process property within the <service> tag for the service in the manifest file. In order to launch a remote service it is also necessary to provide an intent filter for the service. To implement these changes, modify the AndroidManifest.xml file to add the required entries:

<pre>
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ebookfrenzy.RemoteBound"
    android:versionCode="1"
    android:versionName="1.0" >

   <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="17" />

    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name" >
        <activity
            android:label="@string/app_name"
            android:name=".RemoteBoundActivity" >
            <intent-filter >
              <action android:name="android.intent.action.MAIN" />
              <category android:name="android.intent.category.LAUNCHER" />               
            </intent-filter>
        </activity>
         <service android:name=".RemoteService"
             android:process=":my_process" >
             <intent-filter>
                <action android:name="com.example.RemoteService" >
             </action>
          </intent-filter>
          </service>
    </application>

</manifest>
</pre>

<htmlet>android44</htmlet>

== Launching and Binding to the Remote Service ==

As with a local bound service, the client component needs to implement an instance of the ServiceConnection class with onServiceConnected() and onServiceDisconnected() methods. Also in common with local services, the onServiceConnected() method will be passed the IBinder object returned by the onBind() method of the remote service which will be used to send messages to the server handler. In the case of this example, the client is RemoteBoundActivity, the code for which is located in RemoteBoundActivity.java. Load this file and modify it to add the ServiceConnection class and a variable to store a reference to the received Messenger object together with a Boolean flag to indicate whether or not the connection is established:

<pre>
package com.example.remotebound;

import android.app.Activity;
import android.app.ActionBar;
import android.app.Fragment;
import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.view.ViewGroup;
import android.os.Build;
import android.os.IBinder;
import android.os.Message;
import android.os.Messenger;
import android.os.RemoteException;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.content.ServiceConnection;

public class RemoteBoundActivity extends Activity {

	Messenger myService = null;
	boolean isBound;
	
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_remote_bound);
	}

	@Override
	public boolean onCreateOptionsMenu(Menu menu) {
		getMenuInflater().inflate(R.menu.activity_remote_bound, menu);
		return true;
	}

    private ServiceConnection myConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className, 
                                                IBinder service) {
            myService = new Messenger(service);
            isBound = true;
        }

        public void onServiceDisconnected(ComponentName className) {
            myService = null;
            isBound = false;
        }
    };	
}
</pre>

Next, some code needs to be added to bind to the remote service. This involves creating an intent that matches the intent filter for the service as declared in the manifest file and then making a call to the bindService() method, providing the intent and a reference to the ServiceConnection instance as arguments. For the purposes of this example, this code will be implemented in the activity’s onCreate() method:

<pre>
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_remote_bound);

	        if (savedInstanceState == null) {
		     getFragmentManager().beginTransaction()
				.add(R.id.container, 
				new PlaceholderFragment()).commit();
	        }

		
	      Intent intent = new Intent("com.example.RemoteService");
	      bindService(intent, myConnection, Context.BIND_AUTO_CREATE);

	}
</pre>

== Sending a Message to the Remote Service ==

All that remains before testing the application is to implement the sendMessage() method in the RemoteBoundActivity class which is configured to be called when the button in the user interface is touched by the user. This method needs to check that the service is connected, create a bundle object containing the string to be displayed by the server, add it to a Message object and send it to the server:

<pre>
public void sendMessage(View view)
{
	  if (!isBound) return;
        
        Message msg = Message.obtain();
        
        Bundle bundle = new Bundle();
        bundle.putString("MyString", "Message Received");
        
        msg.setData(bundle);
        
        try {
            myService.send(msg);
        } catch (RemoteException e) {
            e.printStackTrace();
        }
}
</pre>

With the code changes complete, compile and run the application. Once loaded, touch the button in the user interface, at which point a Toast message should appear that reads “Message Received”.

== Summary ==

In order to implement interaction between a client and remote bound service it is necessary to implement a handler/message communication framework. The basic concepts behind this technique have been covered in this chapter together with the implementation of an example application designed to demonstrate communication between a client and a bound service, each running in a separate process.



<htmlet>android44</htmlet>



<hr>
<table border="0" cellspacing="0">
<tr>
<td width="20%">[[Android Local Bound Services – A Worked Example|Previous]]<td align="center">[[Android 4 App Development Essentials|Table of Contents]]<td width="20%" align="right">[[An Overview of Android SQLite Databases|Next]]</td>
<tr>
<td width="20%">Android Local Bound Services – A Worked Example<td align="center"><td width="20%" align="right">An Overview of Android SQLite Databases</td>
</table>