You want to create a library that stores Android-agnostic code, and which can be used in your Android and non-Android projects.

Create a JAR-based library that accesses only Java 5 (and earlier) APIs via JDK command-line tools or Eclipse.

Suppose you plan to create a simple library of math-oriented utilities. This library will consist of a single MathUtils class with various static methods. Listing 7-1 presents an early version of this class.

// MathUtils.java

package com.apress.mathutils;

public class MathUtils
{
   public static long factorial(long n)
   {
      if (n <= 0)
         return 1;
      else
         return n*factorial(n-1);
   }
}

MathUtils currently consists of a single static factorial() method for computing and returning factorials (perhaps for use in calculating permutations and combinations). You might eventually expand this class to support fast Fourier transforms and other math operations not supported by the java.lang.Math class.

You've successfully built mathutils.jar and want to learn how to integrate this JAR file into your Eclipse-based Android projects.

You'll create your Eclipse-based Android project with a libs directory and copy mathutils.jar into this directory.

Now that you've created mathutils.jar, you'll need an Android app to try out this library. Listing 7-2 presents the source code to a UseMathUtils single-activity-based app that computes 5-factorial, which the activity subsequently outputs.

// UseMathUtils.java

package com.apress.usemathutils;

import android.app.Activity;

import android.os.Bundle;

import android.widget.TextView;

import com.apress.mathutils.MathUtils;

public class UseMathUtils extends Activity
{
   @Override
   public void onCreate(Bundle savedInstanceState)
   {
      super.onCreate(savedInstanceState);
      TextView tv = new TextView(this);
      tv.setText("5! = "+MathUtils.factorial(5));
      setContentView(tv);
   }
}

Assuming that Eclipse is running, complete the following steps to create a UseMathUtils project:

Eclipse creates a UseMathUtils node in the Package Explorer window. Complete the following steps to set up all files:

You're now ready to run this project. Select Run from the menubar followed by Run from the dropdown menu. If a Run As dialog box appears, select Android Application and click OK. Eclipse starts the emulator, installs this project's APK, and runs the app, whose output appears in Figure 7-1.

Figure 7.1. UseMathUtils's simple user interface could be expanded to let the user enter an arbitrary number.

You want to create a library that stores Android-specific code, such as custom widgets or activities with or without resources.

Android 2.2 and successors let you create Android library projects, which are Eclipse projects describing libraries that incorporate Android-specific code and even resources.

Suppose you want to create a library that contains a single reusable custom widget describing a game board (for playing chess, checkers, or even tic-tac-toe). Listing 7-3 reveals this library's GameBoard class.

// GameBoard.java

package com.apress.gameboard;

import android.content.Context;

import android.graphics.Canvas;
import android.graphics.Paint;

import android.view.View;

public class GameBoard extends View
{
   private int nSquares, colorA, colorB;

   private Paint paint;
   private int squareDim;

   public GameBoard(Context context, int nSquares, int colorA, int colorB)
   {
      super(context);
      this.nSquares = nSquares;
      this.colorA = colorA;
      this.colorB = colorB;
      paint = new Paint();
   }

   @Override
   protected void onDraw(Canvas canvas)
   {
      for (int row = 0; row < nSquares; row++)
      {

paint.setColor(((row & 1) == 0) ? colorA : colorB);
         for (int col = 0; col < nSquares; col++)
         {
            int a = col*squareDim;
            int b = row*squareDim;
            canvas.drawRect(a, b, a+squareDim, b+squareDim, paint);
            paint.setColor((paint.getColor() == colorA) ? colorB : colorA);
         }
      }
   }

   @Override
   protected void onMeasure(int widthMeasuredSpec, int heightMeasuredSpec)
   {
      // keep the view squared
      int width = MeasureSpec.getSize(widthMeasuredSpec);
      int height = MeasureSpec.getSize(heightMeasuredSpec);
      int d = (width == 0) ? height : (height == 0) ? width :
              (width < height) ? width : height;
      setMeasuredDimension(d, d);
      squareDim = width/nSquares;
   }
}

Android custom widgets are based on views that subclass android.view.View or one of its subclasses (such as android.widget.TextView). GameBoard subclasses View directly because it doesn't need any subclass functionality.

GameBoard provides several fields, including the following:

GameBoard's constructor initializes this widget by storing its nSquares, colorA, and colorB arguments in same-named fields, and also instantiates the Paint class. Before doing so, however, it passes its context argument to its View superclass.

Android tells a custom widget to draw itself by calling the widget's overriding protected void onDraw(Canvas canvas) method. GameBoard's onDraw(Canvas) method responds by invoking android.graphics.Canvas's void drawRect(float left, float top, float right, float bottom, Paint paint) method to paint each square for each row/column intersection. The final paint argument determines the color of that square.

Before Android invokes onDraw(Canvas), it must measure the widget. It accomplishes this task by invoking the widget's overriding protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) method, where the passed arguments specify the horizontal and vertical space requirements that are imposed by the parent view. The widget typically passes these arguments to the View.MeasureSpec nested class's static int getSize(int measureSpec) method to return the exact width or height of the widget based on the passed measureSpec argument. The returned values or a modified version of these values must then be passed to View's void setMeasuredDimension(int measuredWidth, int measuredHeight) method to store the measured width and height. Failure to call this method results in a thrown exception at runtime. Because game boards should be square, GameBoard's onMeasure(int, int) method passes the minimum of the width and height to setMeasuredDimension(int, int) to ensure a square game board.

Now that you know how GameBoard works, you're ready to create a library that stores this class. You'll create this library by creating an Android library project. The nice thing about such a project is that it's a standard Android project, so you can create a new Android library project in the same way as you would create a new app project.

Complete the following steps to create the GameBoard project:

Although you create an Android library project in the same fashion as creating a regular app project, you must adjust some of GameBoard's project properties to indicate that it is a library project:

The new GameBoard project is now marked as an Android library project. However, it doesn't yet contain a GameBoard.java source file containing Listing 7-3's contents. Create this source file under Package Explorer's GameBoard/src/com/apress/gameboard node.

You can build this library if you want to (right-click the GameBoard node and select Build Project from the pop-up menu, for example). However, it isn't necessary to do so. The project will be built automatically when you build a project that uses this library. You'll learn how to do this in the next recipe.

You've successfully built the GameBoard library and want to learn how to integrate this library into your Eclipse-based Android projects.

Identify the GameBoard library to Eclipse in the properties of the app project being built, and build the app.

Now that you've created GameBoard, you'll need an Android app to try out this library. Listing 7-4 presents the source code to a UseGameBoard single-activity-based app that instantiates this library's GameBoard class and places it in the activity's view hierarchy.

// UseGameBoard.java

package com.apress.usegameboard;

import android.app.Activity;

import android.graphics.Color;

import android.os.Bundle;

import com.apress.gameboard.GameBoard;

public class UseGameBoard extends Activity
{
   @Override
   public void onCreate(Bundle savedInstanceState)
   {
      super.onCreate(savedInstanceState);
      GameBoard gb = new GameBoard(this, 8, Color.BLUE, Color.WHITE);
      setContentView(gb);
   }
}

Assuming that Eclipse is running, complete the following steps to create a UseGameBoard project:

Eclipse creates a UseGameBoard node in the Package Explorer window. Complete the following steps to set up all files:

You're now ready to run this project. Select Run from the menubar, followed by Run from the dropdown menu. If a Run As dialog box appears, select Android Application and click OK. Eclipse starts the emulator, installs this project's APK, and runs the app, whose output appears in Figure 7-2.

Figure 7.2. UseGameBoard reveals a blue-and-white checkered game board that could be used as the background for a game such as checkers or chess.

You're looking for a simple library that lets your app generate bar charts or line charts.

Although several Android libraries exist for generating charts, you might prefer the simplicity of Kidroid.com's kiChart product (www.kidroid.com/kichart/). Version 0.1 supports bar charts and line charts, and Kidroid promises to add new chart types in subsequent releases.

The link to kiChart's home page presents links for downloading kiChart-0.1.jar (the library) and kiChart-Help.pdf (documentation describing the library).

kiChart's documentation states that bar and line charts support multiple series of data. Furthermore, it states that charts can be exported to image files, and that you can define chart parameters (such as font color, font size, margin, and so on).

The documentation then presents a pair of screenshots to the sample line and bar charts rendered by a demo app. These screenshots are followed by a code exert from this demo – specifically, the LineChart chart activity class.

LineChart's source code reveals the basics of establishing a chart, explained here:

A class diagram that presents kiChart's classes and shows their relationships follows the source code. For example, com.kidroid.kichart.view.ChartView is the superclass of com.kidroid.kichart.view.AxisView, which superclasses BarView and LineView.

Each class's properties and ChartView's public boolean exportImage(String filename) method are then documented. This method lets you output a chart to a file, returning true if successful and false if unsuccessful.

In practice, you'll find kiChart easy to use. For example, consider a ChartDemo app whose main activity (also named ChartDemo) presents a user interface that lets the user enter quarterly sales figures for each of the years 2010 and 2011 via its eight textfields. The main activity also presents a pair of buttons that let the user view this data in the context of a bar chart or in the context of a line chart via separate BarChart and LineChart activities.

Listing 7-5 presents ChartDemo's source code.

// ChartDemo.java

package com.apress.chartdemo;

import android.app.Activity;

import android.content.Intent;

import android.os.Bundle;

import android.view.View;

import android.widget.AdapterView;
import android.widget.Button;

import android.widget.EditText;

public class ChartDemo extends Activity
{
   @Override
   public void onCreate(Bundle savedInstanceState)
   {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

      Button btnViewBC = (Button) findViewById(R.id.viewbc);
      AdapterView.OnClickListener ocl;
      ocl = new AdapterView.OnClickListener()
      {
         @Override
         public void onClick(View v)
         {
            final float[] data2010 = new float[4];
            int[] ids = { R.id.data2010_1, R.id.data2010_2, R.id.data2010_3,
                          R.id.data2010_4 };
            for (int i = 0; i < ids.length; i++)
            {
               EditText et = (EditText) findViewById(ids[i]);
               String s = et.getText().toString();
               try
               {
                  float input = Float.parseFloat(s);
                  data2010[i] = input;
               }
               catch (NumberFormatException nfe)
               {
                  data2010[i] = 0;
               }
            }
            final float[] data2011 = new float[4];
            ids = new int[] { R.id.data2011_1, R.id.data2011_2,
                              R.id.data2011_3, R.id.data2011_4 };
            for (int i = 0; i < ids.length; i++)
            {
               EditText et = (EditText) findViewById(ids[i]);
               String s = et.getText().toString();
               try
               {
                  float input = Float.parseFloat(s);
                  data2011[i] = input;
               }
               catch (NumberFormatException nfe)
               {
                  data2011[i] = 0;
               }
            }
            Intent intent = new Intent(ChartDemo.this, BarChart.class);
            intent.putExtra("2010", data2010);
            intent.putExtra("2011", data2011);
            startActivity(intent);
         }
      };

btnViewBC.setOnClickListener(ocl);

      Button btnViewLC = (Button) findViewById(R.id.viewlc);
      ocl = new AdapterView.OnClickListener()
      {
         @Override
         public void onClick(View v)
         {
            final float[] data2010 = new float[4];
            int[] ids = { R.id.data2010_1, R.id.data2010_2, R.id.data2010_3,
                          R.id.data2010_4 };
            for (int i = 0; i < ids.length; i++)
            {
               EditText et = (EditText) findViewById(ids[i]);
               String s = et.getText().toString();
               try
               {
                  float input = Float.parseFloat(s);
                  data2010[i] = input;
               }
               catch (NumberFormatException nfe)
               {
                  data2010[i] = 0;
               }
            }
            final float[] data2011 = new float[4];
            ids = new int[] { R.id.data2011_1, R.id.data2011_2,
                              R.id.data2011_3, R.id.data2011_4 };
            for (int i = 0; i < ids.length; i++)
            {
               EditText et = (EditText) findViewById(ids[i]);
               String s = et.getText().toString();
               try
               {
                  float input = Float.parseFloat(s);
                  data2011[i] = input;
               }
               catch (NumberFormatException nfe)
               {
                  data2011[i] = 0;
               }
            }
            Intent intent = new Intent(ChartDemo.this, LineChart.class);
            intent.putExtra("2010", data2010);
            intent.putExtra("2011", data2011);
            startActivity(intent);
         }
      };
      btnViewLC.setOnClickListener(ocl);
   }
}

ChartDemo implements all of its logic in its onCreate(Bundle) method. This method largely concerns itself with setting its content view and attaching a click listener to each of the view's two buttons.

Because these listeners are nearly identical, we'll consider only the code for the listener attached to the viewbc (view bar chart) button. In response to this button being clicked, the listener's onClick(View) method is called to perform the following tasks:

Listing 7-6 presents BarChart's source code.

// BarChart.java

package com.apress.chartdemo;

import com.kidroid.kichart.ChartActivity;

import com.kidroid.kichart.model.Aitem;

import com.kidroid.kichart.view.BarView;

import android.graphics.Color;

import android.os.Bundle;

public class BarChart extends ChartActivity
{
   @Override
   public void onCreate(Bundle savedInstanceState)
   {
      super.onCreate(savedInstanceState);
      Bundle bundle = getIntent().getExtras();
      float[] data2010 = bundle.getFloatArray("2010");
      float[] data2011 = bundle.getFloatArray("2011");
      String[] arrX = new String[4];
      arrX[0] = "2010.1";
      arrX[1] = "2010.2";
      arrX[2] = "2010.3";
      arrX[3] = "2010.4";
      Aitem[] items = new Aitem[2];
      items[0] = new Aitem(Color.RED, "2010", data2010);
      items[1] = new Aitem(Color.GREEN, "2011", data2011);
      BarView bv = new BarView(this);
      bv.setTitle("Quarterly Sales (Billions)");
      bv.setAxisValueX(arrX);

bv.setItems(items);
      setContentView(bv);
   }
}

BarChart first obtains a reference to the Intent object passed to it by calling its inherited Intent getIntent() method. It then uses this method to retrieve a reference to the Intent object's Bundle object, which stores the floating-point arrays of data items. Each array is retrieved by invoking Bundle's float[] getFloatArray(String key) method.

BarChart next builds a String array of labels for the chart's X-axis and creates an Aitem array populated with two Aitem objects. The first object stores the 2010 data values and associates these values with the color red and 2010 as the legend value; the second object stores 2011 data values with color green and legend value 2011.

After instantiating BarView, BarChart calls this object's setTitle(String) method to establish the chart's title, setAxisValueX(String[]) method to pass the array of X-axis labels to the object, and setItems(Aitem[]) method to pass the Aitem array to the object. The BarView object is then passed to setContentView() to display the bar chart.

Listing 7-7 presents main.xml, which describes the layout and widgets that comprise ChartDemo's user interface.

<?xml version="1.0" encoding="utf-8"?>
<TableLayout xmlns:android="http://schemas.android.com/apk/res/android"
             android:layout_width = "fill_parent"
             android:layout_height="fill_parent"
             android:stretchColumns="*">
  <TableRow>
    <TextView android:text=""/>
    <TextView android:text="2010"
              android:layout_gravity="center"/>
    <TextView android:text="2011"
              android:layout_gravity="center"/>
  </TableRow>

  <TableRow>
    <TextView android:text="1st Quarter"/>
    <EditText android:id="@+id/data2010_1"
              android:inputType="numberDecimal"
              android:maxLines="1"/>

<EditText android:id="@+id/data2011_1"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
  </TableRow>

  <TableRow>
    <TextView android:text="2nd Quarter"/>
    <EditText android:id="@+id/data2010_2"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
    <EditText android:id="@+id/data2011_2"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
  </TableRow>

  <TableRow>
    <TextView android:text="3rd Quarter"/>
    <EditText android:id="@+id/data2010_3"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
    <EditText android:id="@+id/data2011_3"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
  </TableRow>

  <TableRow>
    <TextView android:text="4th Quarter"/>
    <EditText android:id="@+id/data2010_4"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
    <EditText android:id="@+id/data2011_4"
              android:inputType="numberDecimal"
              android:maxLines="1"/>
  </TableRow>

  <TableRow>
    <TextView android:text=""/>
    <Button android:id="@+id/viewbc"
            android:text="View Barchart"/>
    <Button android:id="@+id/viewlc"
            android:text="View Linechart"/>
  </TableRow>
</TableLayout>

main.xml describes a tabular layout via the <TableLayout> tag, where the user interface is laid out in six rows and three columns. The "fill_parent" assignment to each of this tag's layout_width and layout_height attributes tells this layout to occupy the activity's entire screen. The "*" assignment to this tag's stretchColumns attribute tells this layout to give each column an identical width.

Nested inside <TableLayout> and its </TableLayout> partner are a series of <TableRow> tags. Each <TableRow> tag describes the contents of a single row in the tabular layout, and these contents are a variety of zero or more views (such as TextView and EditText), where each view constitutes one column.

Listing 7-8 presents this app's AndroidManifest.xml file, which describes the app and its activities.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.apress.chartdemo"
          android:versionCode="1"
          android:versionName="1.0">
   <application android:icon="@drawable/icon" android:label="@string/app_name">
      <activity android:name=".ChartDemo"
                android:label="@string/app_name">
         <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
      </activity>
      <activity android:name=".BarChart"/>
      <activity android:name=".LineChart"/>
   </application>
   <uses-sdk android:minSdkVersion="9" />
</manifest>

It's important to include <activity> tags for each of the BarChart and LineChart activities in the manifest. Failure to do so results in a runtime dialog box that displays the following message: "The application Chart Demo (process com.apress.chartdemo) has stopped unexpectedly. Please try again."

Figure 7-3 reveals ChartDemo's main activity with sample values entered for each quarter.

Figure 7.3. ChartDemo lets you enter eight data values and choose to display these values via a bar chart or a line chart.

Clicking the View Barchart button after entering the aforementioned data values launches the BarChart activity, which displays the bar chart shown in Figure 7-4.

Figure 7.4. BarChart displays each array's data values via a series of colored bars.

In addition to presenting a barchart, Figure 7-4 reveals that a trial version of kiChart is being used. You'll need to contact Kidroid.com and find out about licensing and how to obtain a version of kiChart that doesn't display this message.

Google's Cloud-To-Device Messaging (C2DM) framework (http://code.google.com/android/c2dm/index.html), which is designed to implement push messaging to the device, has a number of drawbacks that can impact it as a practical solution for push messaging. Your app needs a more universal push solution.

Utilize IBM's MQTT library to implement lightweight push messaging in your apps. The MQTT client library is offered from IBM in a pure Java implementation, meaning it can be utilized on any Android device, without limitation on specific API Levels.

An MQTT system consists of three main components:

Messages are filtered by topic. Topics are defined in a tree format, represented by a path string. Clients may subscribe to specific topics, or sub-topic groups by providing the appropriate path. For example, suppose we define two topics for our app like so:

examples/one
examples/two

A client may subscribe to either topic by subscribing to the exact full path string. However, if the client prefers to subscribe to both topics (and any others that may be created later in this group), it may conveniently do so by subscribing as follows:

examples/#

The '#' wildcard character indicates that all topics in the examples group are of interest to this client.

In this recipe we'll focus on implementing the client app using the MQTT library on the Android device. IBM provides excellent tools for development and testing of the other components, which we'll expose here as well.

The MQTT Java library may be freely downloaded from IBM at the following location: www-01.ibm.com/support/docview.wss?uid=swg24006006. The download archive contains sample code, API Javadoc, and usage documentation, in addition to the library JAR.

Locate the wmqtt.jar file from within the download archive. This is the library that must be included into the Android project. By convention, this means a /libs directory should be created in your project directory, and this JAR should be inserted there.

For testing your client implementation, IBM provides the Really Small Message Broker (RSMB). RSMB may be downloaded at the following location: www.alphaworks.ibm.com/tech/rsmb.

RSMB is a multi-platform download that includes command-line tools for both the message broker and an application to publish messages. The license provided by IBM for this tool forbids it from being used in a production environment; at that point you will need to roll your own or use one of the many open source implementations available. However, for development of the mobile client, RSMB couldn't be more perfect.

//ClientService.java
package com.apress.pushclient;

import android.app.AlarmManager;
import android.app.PendingIntent;
import android.app.Service;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.Handler;
import android.os.IBinder;
import android.os.Message;
import android.widget.Toast;
//Imports required from the MQTT Library JAR
import com.ibm.mqtt.IMqttClient;
import com.ibm.mqtt.MqttClient;
import com.ibm.mqtt.MqttException;
import com.ibm.mqtt.MqttPersistenceException;
import com.ibm.mqtt.MqttSimpleCallback;

public class ClientService extends Service implements MqttSimpleCallback {

    //Location where broker is running
    private static final String HOST = HOSTNAME_STRING_HERE;
    private static final String PORT = "1883";
    //30 minute keep-alive ping
    private static final short KEEP_ALIVE = 60 * 30;
    //Unique identifier of this device
    privatestaticfinal String CLIENT_ID = "apress/"+System.currentTimeMillis();
    //Topic we want to watch for
    private static final String TOPIC = "apress/examples";

    private static final String ACTION_KEEPALIVE =
"com.examples.pushclient.ACTION_KEEPALIVE";

    private IMqttClient mClient;
    private AlarmManager mManager;
    private PendingIntent alarmIntent;

    @Override
    public void onCreate() {
        super.onCreate();
        mManager = (AlarmManager)getSystemService(Context.ALARM_SERVICE);

        Intent intent = new Intent(ACTION_KEEPALIVE);
        alarmIntent = PendingIntent.getBroadcast(this, 0, intent, 0);

registerReceiver(mReceiver, new IntentFilter(ACTION_KEEPALIVE));

        try {
            //Format: tcp://hostname@port
            String connectionString = String.format("%s%s@%s", MqttClient.TCP_ID, HOST,
PORT);
            mClient = MqttClient.createMqttClient(connectionString, null);
        } catch (MqttException e) {
            e.printStackTrace();
            //Can't continue without a client
            stopSelf();
        }
    }

    @Override
    public void onStart(Intent intent, int startId) {
        //Callback on Android devices prior to 2.0
        handleCommand(intent);
    }

    @Override
    publicint onStartCommand(Intent intent, int flags, int startId) {
        //Callback on Android devices 2.0 and later
        handleCommand(intent);
        //If Android kills this service, we want it back when possible
        return START_STICKY;
    }

    private void handleCommand(Intent intent) {
        try {
            //Make a connection
            mClient.connect(CLIENT_ID, true, KEEP_ALIVE);
            //Target MQTT callbacks here
            mClient.registerSimpleHandler(this);
            //Subscribe to a topic
            String[] topics = new String[] { TOPIC };
            //QoS of 0 indicates fire once and forget
            int[] qos = newint[] { 0 };
            mClient.subscribe(topics, qos);

            //Schedule a ping
            scheduleKeepAlive();
        } catch (MqttException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        unregisterReceiver(mReceiver);
        unscheduleKeepAlive();

        if(mClient != null) {
            try {
                mClient.disconnect();
                mClient.terminate();

} catch (MqttPersistenceException e) {
                e.printStackTrace();
            }
            mClient = null;
        }
    }

    //Handle incoming message from remote
    private Handler mHandler = new Handler() {
        @Override
        public void handleMessage(Message msg) {
            String incoming = (String)msg.obj;
            Toast.makeText(ClientService.this, incoming, Toast.LENGTH_SHORT).show();
        }
    };

    //Handle ping alarms to keep the connection alive
    private BroadcastReceiver mReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            if(mClient == null) {
                return;
            }
            //Ping the MQTT service
            try {
                mClient.ping();
            } catch (MqttException e) {
                e.printStackTrace();
            }
            //Schedule the next alarm
            scheduleKeepAlive();
        }
    };

    private void scheduleKeepAlive() {
        long nextWakeup = System.currentTimeMillis() + (KEEP_ALIVE * 1000);
        mManager.set(AlarmManager.RTC_WAKEUP, nextWakeup, alarmIntent);
    }

    private void unscheduleKeepAlive() {
        mManager.cancel(alarmIntent);
    }

    /* MqttSimpleCallback Methods */

    @Override
    public void connectionLost() throws Exception {
        mClient.terminate();
        mClient = null;
        stopSelf();
    }

    @Override
    public void publishArrived(String topicName, byte[] payload, int qos, boolean
retained) throws Exception {
        //Be wary of UI related code here!
        //Best to use a Handler for UI or Context operations

StringBuilder builder = new StringBuilder();
        builder.append(topicName);
        builder.append('
'),
        builder.append(new String(payload));
        //Pass the message up to our handler
        Message receipt = Message.obtain(mHandler, 0, builder.toString());
        receipt.sendToTarget();
    }

    /*Unused method*/
    //We are not using this service as bound
    //It is explicitly started and stopped with no direct connection
    @Override
    public IBinder onBind(Intent intent) { return null; }
}

Testing the Client

In order to test messaging with the device, you will need to start up an instance of RSMB on your machine. From the command line, navigate into the location where you unarchived the download, and then into the directory that matches your computer's platform (Windows, Linux, Mac OS X). From here, simply execute the broker command and the broker service will begin running on your machine, located at localhost:1883:

CWNAN9999I Really Small Message Broker
CWNAN9997I Licensed Materials - Property of IBM
CWNAN9996I Copyright IBM Corp. 2007, 2010 All Rights Reserved
...

CWNAN0014I MQTT protocol starting, listening on port 1883

At this point, you may connect to the service and publish messages or register to receive messages. To put this Service to the test, Listings 7-10 and 7-11 create a simple Activity that may be used to start and stop the service.

Example 7.10. res/menu/home.xml

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
  <item
    android:id="@+id/menu_start"
    android:title="Start Service" />
  <item
    android:id="@+id/menu_stop"
    android:title="Stop Service" />
</menu>

Example 7.11. Activity Controlling MQTT Service

//ClientActivity.java
package com.apress.pushclient;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;

public class ClientActivity extends Activity {

    private Intent serviceIntent;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        serviceIntent = new Intent(this, ClientService.class);
    }

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

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        switch(item.getItemId()) {
        case R.id.menu_start:
            startService(serviceIntent);
            return true;
        case R.id.menu_stop:
            stopService(serviceIntent);
            return true;
        }

return super.onOptionsItemSelected(item);
    }
}

Listing 7-11 creates an Intent that will be used by two menu options to start and stop the service at will (see Figure 7-5). By pressing the MENU button and selecting "Start Service," the MQTT connection will start up and register the device for messages with the topic "apress/examples."

Figure 7.5. Activity to Control Service

Note

The HOST value in the example service needs to point to the machine where your RSMB instance is running. Even if you are testing in the emulator on the same machine, this value is NOT localhost! At the very least, you must point the emulator or device to the IP address of the machine where your broker is running.

With the Android device successfully registered for push messages from the broker, open up another command line window and navigate to the same directory from where broker was executed. Another command, stdinpub, can be used to connect to the broker instance and publish messages down to the device. From the command line type the following command:

stdinpub apress/examples

This command will register a client to publish messages with a topic matching our example. You will see the following as a result:

Using topic apress/examples
Connecting

Now you may type any message you like, followed by Enter. Upon pressing Enter, the message will be sent to the broker, and pushed out to the registered device. Do this as many times as you like, and then use CTRL-C to break out of the program. CTRL-C will also work to terminate the broker service.

Tip

RSMB also includes a third command, stdoutsub, to subscribe to a set of topics with your local broker service. This command lets you completely close the loop, and test whether problems are occurring in the test suite or in your Android app.