To download the dependencies needed by your project you have at least 3 choices:
1. Let Maven automatically find and download them from Maven Repository – might not all be available
2. Use the maven-android-sdk-deployer which installs the android jars from your SDK into your local repository (~/.m2/repository)
3. Setup your own enterprise repository with Sonatype Nexus, where you can add whatever jar you might need and can’t find on other sources. Then all you need to do is to let Maven know where to look:

   <repositories>
		<repository>
			<id>Nexus</id>
			<url>http://myip:myport/nexus/content/repositories/releases</url>
		</repository>
	</repositories> 

The parent .pom file contains a description of what dependencies will be managed top-level to be used by children projects. This doesn’t actually download them in your local repository, but lets you use a simpler way of including the dependencies later on. For e.g. you can skip specifying the <version/> or even the <groupId/> on some cases.

    <dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>com.google.android</groupId>
				<artifactId>android</artifactId>
				<version>${android.version}</version>
			</dependency>
			<dependency>
				<groupId>com.google.android</groupId>
				<artifactId>android-test</artifactId>
				<version>${android.version}</version>
			</dependency>
			<dependency>
				<groupId>com.google.android</groupId>
				<artifactId>android-support</artifactId>
				<version>${android.support.version}</version>
			</dependency>
			<dependency>
				<groupId>junit</groupId>
				<artifactId>junit</artifactId>
				<version>${junit.version}</version>
			</dependency>
		</dependencies>
	</dependencyManagement>

The dependencies that I’ll need in more than one module are the android jars (for instrumentation tests as well), junit and the android compatibility (support) library.

The same you can do for specifying how certain plugins that are used in the children modules behave inside <pluginManagement/>. For e.g. here’s the android-maven-plugin:

<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<version>${android.maven.plugin.version}</version>

and below is what I’ve configured it to do (with comments):

<configuration>
	<!-- Give the path to your Android SDK and the Android version you're using -->
	<sdk>
		<path>${env.ANDROID_HOME}</path>
		<platform>${android.api.level}</platform>
	</sdk>

	<!-- For the testing phase, this plugin will need to run an emulator called
		'Default', that needs to be available in $HOME/.android/avd/ folder as Default.avd -->
	<emulator>
		<avd>Default</avd>
		<wait>60000</wait>
		<options>-no-boot-anim -wipe-data -no-window</options>
	</emulator>

	<zipalign>
		<verbose>true</verbose>
	</zipalign>

	<!-- ProGuard is a free Java class file shrinker, optimizer, obfuscator,
		and preverifier. It detects and removes unused classes, fields, methods,
		and attributes. It optimizes bytecode and removes unused instructions. It
		renames the remaining classes, fields, and methods using short meaningless
		names.This plugin will read the Proguard configurations inside specified
		file. -->
	<proguard>
		<config>proguard.cfg</config>
	</proguard>

	<!-- Remove the existing .apk from the device/emulator before installing
		the newly built .apk file. -->
	<undeployBeforeDeploy>true</undeployBeforeDeploy>
</configuration>

I opted for not showing the emulator window when running the automated instrumentation tests because I had a strange problem: the emulator starts with the screen lock and the tests are not running properly. If you really need to see the emulator, remove the -no-window option. If you still have the locking problem, here’s a script that sends some key events to the emulator via telnet to simulate unlocking the screen. You can run that script with Exec Maven Plugin like below (put this inside your test project’s pom):

<build>
	<plugins>
		<plugin>
			<groupId>org.codehaus.mojo</groupId>
			<artifactId>exec-maven-plugin</artifactId>
			<version>1.2.1</version>
			<executions>
				<execution>
					<phase>pre-integration-test</phase>
					<goals>
						<goal>exec</goal>
					</goals>
				</execution>
			</executions>
			<configuration>
				<executable>unlock_emulator.sh</executable>
				<workingDirectory>${project.parent.basedir}</workingDirectory>
			</configuration>
		</plugin>
	</plugins>
</build>

The unlocking bash script (I’m not an expert in scripting, but I assume it can be done better in Python or whatever)

host=localhost
port=5554
cmd="event send EV_KEY:KEY_MENU:1 EV_KEY:KEY_MENU:0"

( echo open ${host} ${port}
sleep 1
echo -e "\r"
sleep 1
echo ${cmd}
sleep 1
echo -e "\r"
sleep 1
echo exit ) | telnet

sleep 10

To be continued…

So let’s start with the basics tools. First on my mind was Maven, which is very useful mostly for keeping the project organised, manage the external dependencies, take care of project’s lifecycle from compiling to releasing and deploying etc. You need to install Maven on your workstation and there are many tutorials on how to do that, which is beyond the scope of this blog post.

Maven knows Java projects very well. But for an Android project, you need to tell it what and how to do for different phases like compile and release. For example, when you release you want to be able switch the debug mode off, increment the project version, sign it with a release key, zipalign it etc. Maven knows how to do that thanks to a very useful plugin called android-maven-plugin. This plugin has several goals, ranging from packaging the .apk, running tests on the emulator to deploying the .apk and actually running the application etc.

You can find the documentation needed for using this plugin on their website. The basic usage is to create an Android project and then add a .pom file in which specify, among others, the use of the android-maven-plugin.

In this post I am providing a very small working Android-Maven project with two modules (one for the app and one for the tests). Also I’m gonna tell you how I added Robotium for integration tests and Robolectric for unit tests as well my view regarding which is better later on. There are a few glitches that I’ve struggled with while making this project work, so it might be useful to read on and save some time…if not, jump directly to the source here. Disclaimer: if the project doesn’t work out of the box on your machine, it probably means you have to tweak things here and there like explained below.

Most of us mortals use Eclipse to write Android code because of the ADT plugin. Eclipse Indigo comes bundled with the m2e plugin which is used for enabling the Maven nature on a project. On older Eclipse versions you can install this from Eclipse Marketplace. If you add a .pom file to your normal Android project and you have m2e installed inside Eclipse, then all you have to do is right-click the project and select Configure > Convert to Maven project. So instead of the usual way of managing project dependencies by creating a libs folder inside your project, manually adding the needed .jars in there (and keeping track of versions) and tell Eclipse to add those jars in the build classpath, you enable Maven to take care of those dependencies using a POM file.

The problem I’ve faced right away was that m2e did not recognised the android-maven-plugin by saying something weird like Plugin execution not covered by lifecycle configuration. There is an Android Maven Configurator plugin that makes m2e work with Android. However, I could not fix it by pressing Discover new m2e connectors because it kept saying it can’t find any connectors. So after googling and stackoverflowing I found out that you need to go to Eclipse > Preferences > Maven > Discovery and press Open Catalog. Then you’ll find the Android Connector as the first listing. You install it and it works. Mostly…

Download the sample code or clone it with git from https://github.com/CodeAndMagic/AndroidMagic

Anyway, there are numerous tutorials on how to integrate this library in an Android project, which is pretty simple (just download their jar and include it in the java build path).

What I was interested in this tiny test project was to see if the Smack spawns a new thread when I connect a MessageListener to listen for XMPP messages. That is useful for instance if you have a background Service that keeps a live-connection with a XMPP server in order to process the incoming messages. Since a Service in Android runs on the main thread of their host process, if I want to do intensive CPU or blocking operations (like networking), Android recommends spawning a new thread for them.

So I used this piece of code to connect a MessageListener and observe on which thread are messages received.

@Override
		public void processMessage(final Chat chat, final Message message) {
			Log.i(TAG, "Xmpp message received: '" + message.getBody() + "' on thread: " + getThreadSignature());
			// --> this is another thread ('Smack Listener Processor')
		}

Luckily, it does spawn its own thread (you can observe it in DDMS under the name ‘Smack Listener Processor’) in the Threads tab. So for instance, I think it’s safe to have your message parsed on this thread and then, if you need more expensive operations based on the content of the message, you can do it on a another thread and sync back with the Service’s thread via a Handler when it’s done. You can download the code for the project but you’ll need your own XMPP server to test it out. Enjoy!

android-asmack-test

I was struggling the other day with some basic HTTP calls in Android. The LogCat is not very helpful when you need to monitor your http traffic, especially if you use a third-party library for making the calls and thus you are unable to insert some useful logs where you need them.

The fastest solution I have found is to use Charles and set up a reverse proxy to intercept all the calls made to a specific host. Instead of making the call to the actual server, make the call towards the reverse proxy. This in turn will forward the call to the real domain but will also log the request and response information.

To set this up, enable Reverse Proxies from Charles’ Proxy menu then include the host to which you target your calls in the Recording Settings (the Include tab), for eg. myhostname if the domain is http://myhostname/.

On the Android device you don’t need to modify any wifi settings.

In your service code, you can configure a method to read the base domain for your calls from a resource string, depending if you want to use a reverse proxy and if the application is in debug mode. Something on the line of this:

private static String getDomain() {
		if (Utils.isDebugMode(BaseApplication.getInstance())) {
			// in case you want to use a reverse proxy to sniff the server calls
			final Resources res = BaseApplication.getInstance().getResources();
			if ("yes".equalsIgnoreCase(res.getString(R.string.use_debug_proxy))) {
				return res.getString(R.string.debug_proxy);
			}
		}
		return REAL_DOMAIN;
	}

And the utility method, which simply reads the android:debuggable flag from AndroidManifest.xml, which, if not manually overridden, ADT knows to automatically set to true when you plug in a device with a debuggable usb connection.

	public static boolean isDebugMode(final Context context) {
		final ApplicationInfo info = context.getApplicationInfo();
		final int appFlags = info.flags;
		return (appFlags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;
	}

The debug proxy must be set using your computer’s ip and a given proxy, for e.g: http://192.168.0.13:55699.

It’s a fairly simple process but can save you a fair amount of time while debugging. Enjoy!

I wanted a fragment representing a simple form, with a bunch of TextView as labels and EditText as fields. The real case scenario involved fetching some data over the network and based on that data, building a dynamic form. I thought this was going to be a simple case of using a loader (like AsyncTaskLoader), fetching the data and building the view hierarchy as soon as the loader returned the required information. Since I’m growing fond of using the setRetainInstance() method to automatically save a fragment’s state across screen configuration changes, I thought that this would work in my case without problems.

It turns out I was not paying enough attention to an important method in the fragment’s lifecycle: onCreateView(). This method is called for every fragment that has a view hierarchy in order to instantiate its interface view. Normally,  you inflate an XML layout file and return it as the root of this fragment’s hierarchy.

But there’s a problem. If your view hierarchy is made of dynamically added views, after changing the screen orientation you’d want to keep that hierarchy intact, including all the view’s states (like EditText input, Spinner selection etc.). If you inflate the XML layout again, you will loose all of these views without any chance of saving the user input. So what’s the solution?

It turns out the solution is quite simple. You can keep the root of your hierarchy as a variable in the fragment, so it’s saved after the configuration change. But the thing is, this view is still attached to the old hierarchy, so you need to remove it and re-attach it to the current hierarchy for this saved and resurrected fragment.

 @Override
 public View onCreateView(LayoutInflater inflater, ViewGroup container,
 Bundle savedInstanceState) {
 Log.d(TAG, "onCreateView(): container = " + container
 + "savedInstanceState = " + savedInstanceState);

if (mScrollView == null) {
 // normally inflate the view hierarchy
 mScrollView = (ScrollView) inflater.inflate(R.layout.fragment,
 container, false);
 mFormView = (LinearLayout) mScrollView.findViewById(R.id.form);
 mProgressView = (ProgressBar) mScrollView
 .findViewById(R.id.loading);
 } else {
 // mScrollView is still attached to the previous view hierarchy
 // we need to remove it and re-attach it to the current one
 ViewGroup parent = (ViewGroup) mScrollView.getParent();
 parent.removeView(mScrollView);
 }
 return mScrollView;
 }
 

Another important thing is to remember that if your loader has finished loading the required data when the screen is flipped, it will automatically trigger the onLoadFinished() method. If you build your form there, you should make sure not to duplicate your view hierarchy. The simplest thing to do is to have a boolean variable to keep track of whether that form was built or not.

private void buildForm() {
		// if the view hierarchy was already build, skip this
		if (mDone)
			return;

		addFormField("First Name", InputType.TYPE_TEXT_VARIATION_PERSON_NAME);
		addFormField("Last Name", InputType.TYPE_TEXT_VARIATION_PERSON_NAME);
		addFormField("Age", InputType.TYPE_CLASS_NUMBER);
		addFormField("Phone", InputType.TYPE_CLASS_PHONE);

		// the view hierarchy is now complete
		mDone = true;
	}

Take a look at the source code of this little Android project if you want to test it in action. Enjoy!

android-dynamic-form-fragment.zip

It turns out it’s a pretty straightforward concept – of course, that after you go through a lot of trials and errors, read all the available documentation including the one from the compatibility library’s source code etc…

I’m going to illustrate it below in a simple, but very common case. Let’s suppose I have a button that once pressed, starts fetching some data in a background thread, using an AsyncTaskLoader. Meanwhile, to make my little example more useful, I am displaying a progress dialog with a simple “Loading…” message on top of my activity. If I flip the screen and the background thread still has work to do, I pretty much expect to see the loading dialog “on the other side” (after the screen configuration change). I also expect that my loader is still busy doing the work in background until it’s done, like nothing has happened.

The LoaderManager class has two methods:

public abstract <D> Loader<D> initLoader(int id, Bundle args,
            LoaderManager.LoaderCallbacks<D> callback);

and

public abstract <D> Loader<D> restartLoader(int id, Bundle args,
            LoaderManager.LoaderCallbacks<D> callback);

The first is supposed to start a new loader with the given id or to re-connect with an existing loader with that id. The second one is supposed to start a new loader with the give id OR – and this is different from the initLoader() – re-start an existing loader with that id.

This means, in the case of my AsyncTaskLoader, that if I call restartLoader(), my loader will execute the background work again. If I call initLoader() it WILL NOT execute the background data again, but if that loader has finished its job, it will immediately return the last valid result.

Let’s take a look at the sample below.

@Override
	public void onActivityCreated(Bundle savedInstanceState) {
		super.onActivityCreated(savedInstanceState);
		// this is really important in order to save the state across screen
		// configuration changes for example
		setRetainInstance(true);

		// LoaderManager.enableDebugLogging(true);

		mRes = getResources();
		mInflater = LayoutInflater.from(getActivity());

		mBtnReload = (Button) getActivity().findViewById(R.id.btn);
		mBtnReload.setOnClickListener(new View.OnClickListener() {

			@Override
			public void onClick(View v) {
				// first time
				if (mFirstRun) {

					mFirstRun = false;
					mBtnReload.setText(mRes.getString(R.string.restart));

					startLoading();
				}
				// already started once
				else {
					restartLoading();
				}
			}
		});

		// you only need to instantiate these the first time your fragment is
		// created; then, the method above will do the rest
		if (mAdapter == null) {
			mItems = new ArrayList<String>();
			mAdapter = new MyAdapter(getActivity(), mItems);
		}
		getListView().setAdapter(mAdapter);

		// ---- magic lines starting here -----
		// call this to re-connect with an existing
		// loader (after screen configuration changes for e.g!)
		LoaderManager lm = getLoaderManager();
		if (lm.getLoader(0) != null) {
			lm.initLoader(0, null, this);
		}
		// ----- end magic lines -----

		if (!mFirstRun) {
			mBtnReload.setText(mRes.getString(R.string.restart));
		}
	}

	protected void startLoading() {
		showDialog();

		// first time we call this loader, so we need to create a new one
		getLoaderManager().initLoader(0, null, this);
	}

	protected void restartLoading() {
		showDialog();

		mItems.clear();
		mAdapter.notifyDataSetChanged();
		getListView().invalidateViews();

		// --------- the other magic lines ----------
		// call restart because we want the background work to be executed
		// again
		Log.d(TAG, "restartLoading(): re-starting loader");
		getLoaderManager().restartLoader(0, null, this);
		// --------- end the other magic lines --------
	}

	@Override
	public Loader<Void> onCreateLoader(int id, Bundle args) {
		AsyncTaskLoader<Void> loader = new AsyncTaskLoader<Void>(getActivity()) {

			@Override
			public Void loadInBackground() {
				try {
					// simulate some time consuming operation going on in the
					// background
					Log.d(TAG, "loadInBackground(): doing some work....");
					for (int i = 0; i < SIZE; ++i) {
						mItems.add(WORDS[i]);
					}

					Thread.sleep(SLEEP);
				} catch (InterruptedException e) {
				}
				return null;
			}
		};
		// somehow the AsyncTaskLoader doesn't want to start its job without
		// calling this method
		loader.forceLoad();
		return loader;
	}

	@Override
	public void onLoadFinished(Loader<Void> loader, Void result) {

		mAdapter.notifyDataSetChanged();
		hideDialog();
		Log.d(TAG, "onLoadFinished(): done loading!");

	}

If I comment the magic lines (44 – 47) and I flip the phone to change the layout, from portrait to landscape or vice-versa, my loader state WILL BE LOST (oh no!) and I will never receive the onLoadFinish() callback call to tell me that the job is done. Since I display a loading dialog while the data is being processed in the background, this means that this dialog it will “hang” on the screen forever and ever without being hidden. That is because we need to re-connect - aka initLoader() - with all our current loaders in order to receive feedback after a screen configuration change or whatever made that fragment be restored.

Also, if I replace restartLoader() in the other magic line (line 73) with initLoader(), the second time I press the “Restart” button it WILL NOT do the background work again (meaning to re-add all the items in the list).  So, nothing will happen and the list will remain empty.  If that were a CursorLoader instead, if a previous load would have been completed with valid results, those results will be returned immediately.

That being said, I’m attaching the sources if you want to try out for yourself. Enjoy!

FragmentWithDialog.tar

Scanner in = new Scanner(new BufferedInputStream(getAssets().open("vertexes.off")));
final float[] vertexes = new float[nrVertexes];
for(int i=0;i    vertexes[i] = in.nextFloat();
}

It seems however that this is incredibly slow (it took 30 minutes to read 10,000 floats!) – as tested on the 2.1 emulator. Run on an actual device this is a bit faster but still very slow – order of minutes. On a PC Java application it takes 1 second to read 20,000 floats (with the same code). I profiled it (for 100 floats) and it seems that the calls to nextFloat take all the time. Because of the BufferedInputStream only 2 calls are made to read from the input and they take very little time (35ms/call). However calls to nextFloat take 435ms/call which is huge. By looking at children calls it seems that calls inside NumberFormat and Pattern are the killers. There are a lot of memory allocations and the Android VM and GC doesn’t seem to be as optimized  as the PC one.

As a solution I found the following to work very well: first I parse my input file on the PC and transform it into binary data, then I read it on the device byte by byte (buffered) and reconstruct the numbers. This is MUCH faster. It takes 1.5s to read 20,000 floats. I say it’s a enormous improvement from 1 hour

Have a look at this StackOverflow discussion for more ideas.

In these circumstances, i asked myself if all calls to a non-direct reference are slower. I’m not an expert at low level stuff, but it looks to me that calling a method through a interface reference is about the same thing as calling a method through a reference to a parent class. But this would mean that we shouldn’t use inheritance at all. And that, for someone like me that usually trades performance for scalability, it sounds crazy.

I decided to make a quick test to see if this is true. You can check the code I used on Pastebin.

First I ran it on my PC and I was stupefied to find results like these at every run (values are in nanoseconds necessary to run 1,000,000,000 method calls):

Then I tested it in an Android application, using a HTC Hero Phone. (Note: I reduced the number of iterations from 1000000000L to 5000000L).

So the interfaces are slower. I can now confirm with my own test. I guess the virtual machine is quite different.
The good thing is that calls through parent references are not slower. Wohoo! OOP for life

Note: I also re-run the test to include a final method call that should be the only one non-virtual. I could not notice any improvement which is at least weird. Posted a question on JavaRanch. Maybe someone can come with a explanation for this.

Well, there’s a simple solution for making this work. What you need is basically to use a TabHost to hold both the TabWidget (which are the actual tab labels) and their content. Since the TabHost is nothing more than a View, you can place that anywhere, including in the root of a fragment defined in XML, like the one below (tabs_fragment.xml). I am hoping the comments in the code are self-explanatory enough.

<?xml version="1.0" encoding="utf-8"?>
<TabHost
	xmlns:android="http://schemas.android.com/apk/res/android"
	android:id="@android:id/tabhost"
	android:layout_width="fill_parent"
	android:layout_height="fill_parent"
	android:background="#EFEFEF">

	<LinearLayout
		android:orientation="vertical"
		android:layout_width="fill_parent"
		android:layout_height="fill_parent">

		<TabWidget
			android:id="@android:id/tabs"
			android:layout_width="fill_parent"
			android:layout_height="wrap_content" />

			<FrameLayout
				android:id="@android:id/tabcontent"
				android:layout_width="fill_parent"
				android:layout_height="fill_parent">

				<FrameLayout
					android:id="@+id/tab_1"
					android:layout_width="fill_parent"
					android:layout_height="fill_parent" />

				<FrameLayout
					android:id="@+id/tab_2"
					android:layout_width="fill_parent"
					android:layout_height="fill_parent" />

			</FrameLayout>
	</LinearLayout>
</TabHost>

Don’t forget to use the correct ids (@android:id/tabhost, @android:id/tabs and @android:id/tabcontent) because the TabHost expects exactly these in order to retrieve the references for each component of the view. If you want to use a custom style for your tabs, it is easy to do so by creating a tab_selector.xml in /res/drawables in which you can use different colors or backgrounds for each tab state. You can find an example in the attached zip.

The equivalent code for actually creating the tabs is in TabsFragment.java below.

package org.codeandmagic.android;

import android.app.Activity;
import android.os.Bundle;
import android.support.v4.app.Fragment;
import android.support.v4.app.FragmentManager;
import android.util.Log;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.TabHost;
import android.widget.TabHost.OnTabChangeListener;
import android.widget.TabHost.TabSpec;
import android.widget.TextView;

public class TabsFragment extends Fragment implements OnTabChangeListener {

	private static final String TAG = "FragmentTabs";
	public static final String TAB_WORDS = "words";
	public static final String TAB_NUMBERS = "numbers";

	private View mRoot;
	private TabHost mTabHost;
	private int mCurrentTab;

	@Override
	public void onAttach(Activity activity) {
		super.onAttach(activity);
	}

	@Override
	public View onCreateView(LayoutInflater inflater, ViewGroup container,
			Bundle savedInstanceState) {
		mRoot = inflater.inflate(R.layout.tabs_fragment, null);
		mTabHost = (TabHost) mRoot.findViewById(android.R.id.tabhost);
		setupTabs();
		return mRoot;
	}

	@Override
	public void onActivityCreated(Bundle savedInstanceState) {
		super.onActivityCreated(savedInstanceState);
		setRetainInstance(true);

		mTabHost.setOnTabChangedListener(this);
		mTabHost.setCurrentTab(mCurrentTab);
		// manually start loading stuff in the first tab
		updateTab(TAB_WORDS, R.id.tab_1);
	}

	private void setupTabs() {
		mTabHost.setup(); // you must call this before adding your tabs!
		mTabHost.addTab(newTab(TAB_WORDS, R.string.tab_words, R.id.tab_1));
		mTabHost.addTab(newTab(TAB_NUMBERS, R.string.tab_numbers, R.id.tab_2));
	}

	private TabSpec newTab(String tag, int labelId, int tabContentId) {
		Log.d(TAG, "buildTab(): tag=" + tag);

		View indicator = LayoutInflater.from(getActivity()).inflate(
				R.layout.tab,
				(ViewGroup) mRoot.findViewById(android.R.id.tabs), false);
		((TextView) indicator.findViewById(R.id.text)).setText(labelId);

		TabSpec tabSpec = mTabHost.newTabSpec(tag);
		tabSpec.setIndicator(indicator);
		tabSpec.setContent(tabContentId);
		return tabSpec;
	}

	@Override
	public void onTabChanged(String tabId) {
		Log.d(TAG, "onTabChanged(): tabId=" + tabId);
		if (TAB_WORDS.equals(tabId)) {
			updateTab(tabId, R.id.tab_1);
			mCurrentTab = 0;
			return;
		}
		if (TAB_NUMBERS.equals(tabId)) {
			updateTab(tabId, R.id.tab_2);
			mCurrentTab = 1;
			return;
		}
	}

	private void updateTab(String tabId, int placeholder) {
		FragmentManager fm = getFragmentManager();
		if (fm.findFragmentByTag(tabId) == null) {
			fm.beginTransaction()
					.replace(placeholder, new MyListFragment(tabId), tabId)
					.commit();
		}
	}

}

Now that you have the content of your fragment in place, you need to create the tab’s children (which are fragments, like the title says). You can subclass the  android.support.v4.app.Fragment (I used a ListFragment in this example). You can also use loaders if your fragment needs to do some background work. In the example below, I use an AsyncTaskLoader to simulate a time-consuming operation in background, at the end of which some words or numbers are added into the list’s adapter and displayed inside a tab. You also need a LoaderCallback object (or your fragment can directly implement this interface) in order to communicate with the LoaderManager to create your loader and also know when its job is done.

package org.codeandmagic.android;

import java.util.ArrayList;
import java.util.List;

import android.content.Context;
import android.os.Bundle;
import android.support.v4.app.ListFragment;
import android.support.v4.app.LoaderManager.LoaderCallbacks;
import android.support.v4.content.AsyncTaskLoader;
import android.support.v4.content.Loader;
import android.util.Log;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.TextView;

public class MyListFragment extends ListFragment implements
		LoaderCallbacks<Void> {

	private static final String TAG = "FragmentTabs";

	private String mTag;
	private MyAdapter mAdapter;
	private ArrayList<String> mItems;
	private LayoutInflater mInflater;
	private int mTotal;
	private int mPosition;

	private static final String[] WORDS = { "Lorem", "ipsum", "dolor", "sit",
			"amet", "consectetur", "adipiscing", "elit", "Fusce", "pharetra",
			"luctus", "sodales" };
	private static final String[] NUMBERS = { "I", "II", "III", "IV", "V",
			"VI", "VII", "VIII", "IX", "X", "XI", "XII", "XIII", "XIV", "XV" };

	private static final int SLEEP = 1000;

	private final int wordBarColor = R.color.word_bar;
	private final int numberBarColor = R.color.number_bar;

	public MyListFragment() {
	}

	public MyListFragment(String tag) {
		mTag = tag;
		mTotal = TabsFragment.TAB_WORDS.equals(mTag) ? WORDS.length
				: NUMBERS.length;

		Log.d(TAG, "Constructor: tag=" + tag);
	}

	@Override
	public void onActivityCreated(Bundle savedInstanceState) {
		super.onActivityCreated(savedInstanceState);
		// this is really important in order to save the state across screen
		// configuration changes for example
		setRetainInstance(true);

		mInflater = LayoutInflater.from(getActivity());

		// you only need to instantiate these the first time your fragment is
		// created; then, the method above will do the rest
		if (mAdapter == null) {
			mItems = new ArrayList<String>();
			mAdapter = new MyAdapter(getActivity(), mItems);
		}
		getListView().setAdapter(mAdapter);

		// initiate the loader to do the background work
		getLoaderManager().initLoader(0, null, this);
	}

	@Override
	public Loader<Void> onCreateLoader(int id, Bundle args) {
		AsyncTaskLoader<Void> loader = new AsyncTaskLoader<Void>(getActivity()) {

			@Override
			public Void loadInBackground() {
				try {
					// simulate some time consuming operation going on in the
					// background
					Thread.sleep(SLEEP);
				} catch (InterruptedException e) {
				}
				return null;
			}
		};
		// somehow the AsyncTaskLoader doesn't want to start its job without
		// calling this method
		loader.forceLoad();
		return loader;
	}

	@Override
	public void onLoadFinished(Loader<Void> loader, Void result) {

		// add the new item and let the adapter know in order to refresh the
		// views
		mItems.add(TabsFragment.TAB_WORDS.equals(mTag) ? WORDS[mPosition]
				: NUMBERS[mPosition]);
		mAdapter.notifyDataSetChanged();

		// advance in your list with one step
		mPosition++;
		if (mPosition < mTotal - 1) {
			getLoaderManager().restartLoader(0, null, this);
			Log.d(TAG, "onLoadFinished(): loading next...");
		} else {
			Log.d(TAG, "onLoadFinished(): done loading!");
		}
	}

	@Override
	public void onLoaderReset(Loader<Void> loader) {
	}

	private class MyAdapter extends ArrayAdapter<String> {

		public MyAdapter(Context context, List<String> objects) {
			super(context, R.layout.list_item, R.id.text, objects);
		}

		@Override
		public View getView(int position, View convertView, ViewGroup parent) {
			View view = convertView;
			Wrapper wrapper;

			if (view == null) {
				view = mInflater.inflate(R.layout.list_item, null);
				wrapper = new Wrapper(view);
				view.setTag(wrapper);
			} else {
				wrapper = (Wrapper) view.getTag();
			}

			wrapper.getTextView().setText(getItem(position));
			wrapper.getBar().setBackgroundColor(
					mTag == TabsFragment.TAB_WORDS ? getResources().getColor(
							wordBarColor) : getResources().getColor(
							numberBarColor));
			return view;
		}

	}

	// use an wrapper (or view holder) object to limit calling the
	// findViewById() method, which parses the entire structure of your
	// XML in search for the ID of your view
	private class Wrapper {
		private final View mRoot;
		private TextView mText;
		private View mBar;

		public Wrapper(View root) {
			mRoot = root;
		}

		public TextView getTextView() {
			if (mText == null) {
				mText = (TextView) mRoot.findViewById(R.id.text);
			}
			return mText;
		}

		public View getBar() {
			if (mBar == null) {
				mBar = mRoot.findViewById(R.id.bar);
			}
			return mBar;
		}
	}
}

Now, all you need to do is create a FragmentActivity to accommodate your tabs fragment. You can either instantiate the fragment programmatically using the methods in the FragmentManager or by putting it directly in XML, like below (main.xml).

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
	xmlns:android="http://schemas.android.com/apk/res/android"
	android:orientation="vertical"
	android:layout_width="fill_parent"
	android:layout_height="fill_parent">

	<fragment
		class="org.codeandmagic.android.TabsFragment"
		android:id="@+id/tabs_fragment"
		android:layout_width="fill_parent"
		android:layout_height="fill_parent" />
</LinearLayout>

With that, your job is pretty much done. You can see  in the screenshot the result and also can download the project that’s available in the attached zip. Enjoy!

FragmentTabs.tar

1. Call populate() for batch operations

After each change the maps api says to call populate() on the overlay. This method basically recalculates and redisplays everything. The problem is that many of the people that posted code samples on the internet took it literally. After each item addition/removal they call populate so if you’re adding 100 items at once, they call populate after each add. Instead, populate should be more like a transaction commit. After you added all 100 items, then you should finish with a populate. This will considerably speed things up.

2. Properly handle changes

As I said, the api was probably made with the idea the the items don’t change much. For exemple, if you remove an item weird stuff start to happend. The map will get properly drawn but if you press in the place where the removed item was you might (or not) get this exception:

ERROR/AndroidRuntime(16446): java.lang.ArrayIndexOutOfBoundsException
ERROR/AndroidRuntime(16446):     at com.google.android.maps.ItemizedOverlay.maskHelper(ItemizedOverlay.java:562)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.ItemizedOverlay.setFocus(ItemizedOverlay.java:365)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.ItemizedOverlay.focus(ItemizedOverlay.java:539)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.ItemizedOverlay.onTap(ItemizedOverlay.java:455)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.OverlayBundle.onTap(OverlayBundle.java:83)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.MapView$1.onSingleTapUp(MapView.java:347)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.GestureDetector.onTouchEvent(GestureDetector.java:533)
ERROR/AndroidRuntime(16446):     at com.google.android.maps.MapView.onTouchEvent(MapView.java:647)

To solve this I discovered that together with populate you need to reset the last focused item:

public void doPopulate(){
    populate();
    setLastFocusedIndex(-1);
}

3. Filter pins by zoom level

If you have hundreds or thousands of items at once, most of them in the same area, the map will do a pretty good job optimizing when you’re zoomed in so that you see only few of them. But if you try to zoom out, the map will try to display all of them. Besides the visual mess of having them on top of each other, the map will start to scroll really really slow.

Many overlay items don't look good at lower zoom levels and reduce performance.

So what I tried is to filter them based on the zoom level. It’s obvious that once you’re so far zoomed out that your screen can fit a continent, you can use only one item to represent a city. Once you get to a workable zoom level, all of them should be displayed. What’s in between though is specific to your application and should be done with great care so that the user doesn’t miss anything. In my case, all the items had the same importance so I used an exponential increase together with a dispersion algorithm to cover a greater geographical area. This way all neighborhoods would contain items.

It better to filter out items if the user can't use them at that zoom level.

To get you started with filtering here’s some code. First you need a interface for the ones listening to zoom events.

public interface ZoomListener {
	public void onZoom(int oldZoom, int newZoom);
}

Yes, Google Api has something like this (OnZoomListener) but it only notifies you when a zoom in/out button is pressed, not when the user pinches the map. So you need a custom MapView to use not only that, but also detect pinch to zoom events and call a more useful callback (some code removed for visibility):

public class ArtMapView extends MapView implements OnZoomListener {
	private int zoom;
	private ZoomListener zoomListener;
	public void setZoomLevel(int zoom) {
		this.zoom = zoom;
		this.getController().setZoom(zoom);
	}
	public ZoomListener getZoomListener() {
		return zoomListener;
	}
	public void setZoomListener(ZoomListener listener) {
		this.zoomListener = listener;
		this.getZoomButtonsController().setOnZoomListener(this);
	}
	public boolean onTouchEvent(MotionEvent event) {
		boolean result = super.onTouchEvent(event);
		if (event.getAction() == MotionEvent.ACTION_UP) {
			checkForZoomEvent();
		}
		return result;
	}
	private void checkForZoomEvent() {
		if (this.zoomListener != null) {
			int newZoom = this.getZoomLevel();
			if (newZoom != zoom) {
				this.zoomListener.onZoom(zoom, newZoom);
			}
			zoom = newZoom;
		}
	}
	public void onZoom(boolean zoomIn) {
		int oldZoom = this.zoom;
		this.setZoomLevel(oldZoom + (zoomIn ? 1 : -1));
		if (this.zoomListener != null) {
			this.zoomListener.onZoom(oldZoom, this.zoom);
		}
	}
}

In the place that constructs your MapView (probably an Activity) you need to implement the zoom listener and start listening to events. On each zoom change you recalculate the number of items to be displayed. One simple way to do it is shown below.

private void getNrPinsToDisplay(List items) {
	if (items == null || items.size() == 0) return;
	int allNrPins = items.size();
	if (newZoom  ZOOM_MAX_LEVEL)
		nrPinsForZoomLevel = allNrPins;
	else
		nrPinsForZoomLevel = MAX_PINS_PER_ZOOM[newZoom - ZOOM_MIN_LEVEL - 1];
}

ZOOM_MIN_LEVEL is the zoom level under which only 1 item is shown (per group of data – example per city)
ZOOM_MAX_LEVEL is the zoom level over which all items are shown
ZOOM_MAX_LEVEL is an array which contains the number of items to be display for the levels in between

All you have to do next is to hook the magic nrPinsForZoomLevel value in the item display function. You can have a look at the ArtAround project on GitHub to see a sample of this being used. There’s room for a lot of improvement and inovation but hope this gave you a few good ideas to get you started.