Getting Started

MXQuery is provided as a library that can be included in standard Android projects. In order to use, please do the following steps:

1. Obtain the latest version of mxquery-android.jar
   1. If you want, attach the source code (mxquery-android-source.jar); good for debugging
2. Create a new Android project (http://developer.android.com/guide/developing/projects/index.html)
3. Add the MXQuery on Android library to your project
4. Start using synchronous or asynchronous XQuery

Your first XQuery code snippet

The library contains a class ch.ethz.mxquery.android.MXQuery as its main interface to the Android Java SDK. If you want to use XQuery in one of your Android activities, call MXQuery.init(this) at the beginning of the onCreate method to register the respective activity with MXQuery (the same applies for onResume, if you make use of it). A complete “Hello, World!” program would look like this:

package ...

import ...

import ch.ethz.mxquery.android.MXQuery;

public class HelloWorld extends Activity {

 @Override

 public void onCreate(Bundle savedInstanceState) {

 super(savedInstanceState);

 MXQuery.init(this);

 TextView tv = new TextView(this);

 this.setContentView(tv);

 tv.setText(MXQuery.doQuery("'Hello, World!'"));

 }

}

Synchronous XQuery

To use XQuery in a synchronous way, just use MXQuery.doQuery(…), as seen in the “Hello, World!” program above, with any query you can imagine. This functionality also supports the XQuery Updating Facility and Scripting extension.

If you want to implement query execution manually, we would like to refer to the Code Examples page. Please be aware that synchronous XQuery might affect the responsiveness of your application, depending on the size of the queries used!

Asynchronous XQuery

Asynchronous XQuery should be the preferred way to use in Android. For this purpose, the MXQuery library provides an implementation of an Android Service. First, add this service to the <application> tag of your Android Manifest.

<application …>
…
<service android:name=”ch.ethz.mxquery.android.MXQueryService”/>
</application>

Then, use it in your activity as follows:

package ...

import ...

import ch.ethz.mxquery.android.MXQueryService

import ch.ethz.mxquery.android.MXQueryService.MXQueryServiceBinder;

import ch.ethz.mxquery.android.XQueryListener;

public class ServiceExample extends Activity {

 protected TextView mTextView;

 protected MXQueryService mService;

 protected boolean mIsBound = false;

 @Override

 public void onCreate(Bundle savedInstanceState) {

 super.onCreate(savedInstanceState);

 MXQuery.init(this);

 mTextView = new TextView(this);

 this.setContentView(mTextView);

 if(!mIsBound)

 doBindService();

 }

 /* Defines callback for runQuery() */

 protected XQueryListener queryListener = new XQueryListener() {

 public void newXQueryResult(final String result) {

 runOnUiThread(new Runnable() {

 public void run() {

 mTextView.setText(result);

 }

 });

 }

 };

 /**

* Defines callbacks for service binding, passed to

* bindService()

*/

 private ServiceConnection mConnection = new ServiceConnection(){
 @Override
 public void onServiceConnected(ComponentName className,

IBinder service) {

 // We've bound to XQueryService, cast the IBinder and

//get XQueryService instance

 MXQueryServiceBinder binder =

(MXQueryServiceBinder) service;

 mService = binder.getService();
 mIsBound = true;

 // Run the query
 String query = "'Hello, XQuery!'";
 mService.runQuery(query, queryListener);
 }

 @Override
 public void onServiceDisconnected(ComponentName cn) {
 mIsBound = false;
 }
 };

 void doBindService() {
 bindService(new Intent(ServiceExample.this,

MXQueryService.class), mConnection,

Context.BIND_AUTO_CREATE);

 mIsBound = true;

 }

}

When manipulating layout elements, it is extremely important to use the runOnUiThread(Runnable) method of the Activity class in order to avoid threading conflicts and crashing apps.

You can also create the necessary Service and Listener implementations manually. Instructions on how to do this can be found on the Code Examples page. That page also contains example code for using the AsyncTask class to execute XQuery. However, the use of AsyncTasks is not recommended, as it has certain disadvantages as compared to Android Services.