A SQL Anywhere Push Sample for Android
This sample uses the Google Cloud to Device Messaging Framework (C2DM) to push data changes from a SQL Anywhere database running on your desktop to an Android application. It shows you how to add push capability to your own SQL Anywhere application on Android.
To get this sample to work, you first need to register for two services. Each of these services needs to recognize your application, and see that is different from anyone else who has downloaded and is using this sample, so the registration needs to be done by you rather than by Sybase.
- Sybase Hosted Relay Server. The relay server lets Android phones on public networks connect to a MobiLink server on your machine, even if there are firewalls between. You can register here; some instructions are here.
- Google C2DM. C2DM is the push service for Android. You can register here.
In addition, you need to have some development tools:
- A SQL Anywhere 12 installation such as the Developer Edition, available for free download here. This tutorial assumes that you have some experience with MobiLink.
- A Java 1.6 or later JDK.
- The Android SDK, downloadable from here.
- The Google APIs add-on for Android emulator images, downloadable from here, if you wish to run the sample in an emulator.
- The Apache HTTP Components libraries, which can be downloaded from here.
And, of course, you need the sample code itself. Here is a zip file that has the source code for this sample application. Unzip it to create a folder named distrib, which you can rename or move. The two subfolders are db (the server-side code and database) and client (the client side code).
Finally, you will need an Android phone. You can run the application on any Android device, or on the Android emulator that comes with the Android JDK. Some company firewalls, however, block the port that push messages use, so you may need a phone with a plan to see the push capability at work.
The sample application is a simple message sending application. Random text messages (constructed from Latin words) are generated at the server, and a push system delivers them to the Android device.
At each stage of this walkthrough, you may need to customize the batch files and source code to reflect your own setup.
Customize the Java source code
You must edit the Java Source code to include your own C2DM account information. Open db\ml_c2db\src\com\sybase\c2dm\MessageSender.java and fill in the correct strings for C2DM_EMAIL and C2DM_PASSWORD.
Build the server
The first step is to build the server-side database and logic. The build process builds the following:
- The consolidated database, which is a SQL Anywhere database that holds a table for messages, a table for information about each user, and a set of tables/stored procedures that generate messages and fill the messages table. The database also has a trigger so that whenever a message is added (or deleted) a table called PushRequest is updated. The PushRequest table holds, for each user, a timestamp for the most recent message to that user.
- A Java package that is run by the MobiLink server.
- An ODBC Data source definition, which the MobiLink server uses when connecting to the consolidated database.
- An UltraLite database, which has the same schema as the database on the Android device. It can be used for desktop testing.
To build the server-side database and logic, open a command prompt, change directory to the db folder, and run build.bat.
If you have problems running build.bat, you may need to edit the file to set the environment variables that point to your SQL Anywhere installation, and you may need to edit the build.bat file in db\ml_c2dm, which contains environment variables for your JDK installation as well as the location of the Apache HTTP components JAR files.
Customize the MobiLink server command line
You must provide the MobiLink server with your Relay Server information. Create a file in the db folder named C2DM.config with the information from your hosted relay server account. It will look like this:
Start the MobiLink server
From the db folder, run mobilink.bat to start the server.
If you have problems, you may need to edit the file to set the local environment variable that points to your JDK installation directory. You may also need to change the lines that include location of the Apache HTTP components. Note that mobilink.bat contains a commented-out line that would set an appropriate setting for debugging the Java code from Eclipse. The batch file sets logging verbosity to high for debugging purposes, but if you are interested in performance you should edit the mobilink.bat file to reduce the logging verbosity (-v option).
Part of the startup code for the MobiLink Java classes is to execute the ClientLoginTokenFactory.getToken() method, which sends the Sender ID and password to Google C2DM servers, and retrieves a token that MobiLink supplies as authorization when sending any subsequent messages.
Test the synchronization setup
Once the MobiLink server is started properly, you can test synchronization using the sync_ul.bat file. This file synchronizes the MobiLink server to the C2DM.udb file created as part of the build. It doesn’t test the push part of this sample, but it does confirm that synchronization is working properly. A successful synchronization is shown as a message in the MobiLink server console window; errors will be logged in the file mobilink.mls, on lines starting with E. If you have problems with this synchronization, you may need to edit the file build_ul.sql and change the synchronization profile definition.
You can inspect the data in the databases by running the isql.bat file in the db folder, which starts one instance of Interactive SQL connected to the SQL Anywhere database, and one connected to the UltraLite database. Again, you may need to edit the file to set environment variables.
At this stage, there are a few messages in the consolidated database, but no additional messages are being generated.
The next step is to build the Android application and test it.
Customize the Android application
From Eclipse, with the Android SDK, open the project in the client folder. You will need to supply your own Relay Server information (so that the application can synchronize with your MobiLink server) and you will need to supply your own C2DM information (so that the application can register with the C2DM system and be matched up with your MobiLInk server.
- In com.sybase.c2dm\C2DM.java, supply the ML_URL_SUFFIX needed for your Relay Server. It will be something like /ias_relay_server/client/rs_client.dll/yourname-yourproject.
- In the same file, edit the C2DM_SENDER_ID field to include our C2DM email. There is no need to supply the password on the client side.
You should now be able to build the application.
Build and run the Android application
In order to run the application, you must run it on a device or emulator that has the Google APIs installed. Essentially all devices have these APIs, but you may need to download a special emulator add-on (as described at the top of this article) to use them on an emulator. You must have a Google ID (email address) to access the Google servers.
Once you start the application, you should see a synchronization take place (watch the console of the MobiLink server) and some messages (random Latin words) appear on the screen. You can carry out an explicit synchronization by choosing Menu > Synchronize. At this stage there will be no notifications, as no new messages are being generated. Once you have synchronization working, you can generate new messages so that push is used.
The application uses AsyncTask objects to carry out database operations on a background thread, leaving the UI thread active. After creating the database, DatabaseTasks.CreateOrReplaceDatabaseTask.onPostExecute() calls C2DM.requestC2DMRegistrationID(), which posts a request to the C2DM servers for a registration ID that identifies the device to the servers. The C2DMReceiver class handles the response from the server, stores the registration ID in the UserDevice table of the application, and synchronizes it to the MobiLink server. Once this synchronization is complete, the MobiLink server can send messages to the device using the registration ID.
Start generating messages
From a command prompt in the db folder, run “isql.bat sa” to open up an Interactive SQL window on the consolidated database. Enter the following command to start generating messages.
alter event add_messages
You can watch messages being added to the message table by executing “SELECT COUNT(*) FROM messages”. Also, you can see the PushRequest table being updated by executing “SELECT * FROM PushRequest”. To see the actions of the MobiLink server, execute “SELECT * FROM PushLog ORDER BY log_id DESC”
At this point, new messages for a user prompt a push message from the MobiLink server to the Android application. On receiving the message, the application synchronizes and then notifies the user with a sound. On the emulator, the sound is not played.
The sample does not include code to update the display after the message is received. You can check that messages are received by choosing Menu > Refresh on the device, or by changing the orientation of the device (which prompts a refresh). To change the orientation of the emulator, press Ctrl+F11.
If you are running the application on an emulator or on a device running WiFi on a company LAN, then a firewall that blocks port 5228 will prevent push messages getting to the application.
So that’s the complete sample. It’s not simple, but it shows, I hope, that you can add push features to SQL Anywhere application for Android, integrating the client and the server into the Google Cloud-to-Device Messaging system.
The sample code is not complete – it does not have sufficient error checking or consideration of all possible cases for a production application, but it does cover the essentials of a push application.