Developers: Implementing Connectors

GeOrg can display cache-data gathered from external sources (websites, databases, etc) in realtime. This data is mainly shown on the Map-Page and on the Find Nearby-Page. It’s helpful if you’d like to go caching spontaneously without having prepared a GPX-file.

These external sources are made available to GeOrg by a mechanism we call “Connector”. Connectors are implemented as android content providers and may register with an existing GeOrg installation. There’s a handful of queries that such a connector has to implement to be able to serve data for GeOrg.

We offer the sourcecode of an example connector for download (Version: 1.0.9) with a full connector-implementation to get you started. It showcases queries against Groundspeaks GoogleMaps-Mashup-Interface. The zip-file contains a complete eclipse-project that you can build on your machine and deploy to your Android phone. You could also deploy it to an emulator but since you don’t have GeOrg there to call it, that’s just good for testing and debugging. If you need more information please continue to read.

Concept

Connectors serve data that is displayed by GeOrg mainly in the map and on the Find Nearby Page. They use an Android-specific mechanism called “Content Provider”. In short a request is sent by GeOrg to an URI that the Connector subscribes to. The Connector parses the parameters and decides what action to take. The result of the call is then returned to GeOrg as a MatrixCursor which is kind of like a SQL-Cursor only without a database backend.

For GeOrg to know your Connector you have to register with GeOrg at some time. Within this registration you tell GeOrg your URI and GeOrg checks if it is valid with a callback request.
The sample does that whenever the user opens the Connector-application. Something the user has to do anyway to enter needed settings. So you can register with GeOrg as often as you want as long as you always use the same URI.

You have to implement four different actions. That means that your Connector must at least answer these 4 different requests, even if it only returns an error or an empty result. These actions are:

  • cacheByCoord – Must return caches within a certain geographic rectangle.
  • cacheDetails – Must return further details for a cache from the resultset returned by cacheByCoord()
  • readGPX – Must return GPX-data for a cache requested with a GC Code as a string.
  • ping – Must return OK so GeOrg can check the validity of your URI.

Recommended reading

Concerning development with Android there is a plethora of information at http://developer.android.com. Most importantly the Dev Guide and the Reference.

If you are new to Android, you will probably best do the following:

  1. Download and install the Eclipse IDE for Java Developers.
  2. Download and install the Android 1.6 SDK and the Android Plugin for Eclipse (ADT). The link contains information for both.
  3. Fire up Eclipse and create a workspace for your Android projects anywhere on disc. Eclipse will ask you to create a workspace when you first start it.
  4. Go through the Hello, Android-Sample which will get you the emulator, a basic feeling for what’s what in the IDE and information about how to run Android projects.
  5. If you get an error about “.class compatibility”, make sure you have set the compiler to JDK 1.5-compliance. You can do this here:
    Window-Menu -> Preferences -> Java -> Compiler -> Compiler compliance level. Set this to “1.5″.

Running the sample

Ok, you downloaded the connector sample and got Hello, Android up and running. How do you open the sample-project?

  1. Unzip the connector-sample.zip you downloaded earlier into your workspace. Make sure you retain the directory structure of the zip-file
  2. In Eclipse choose File-Menu -> Import and from the dialog General -> Existing Projects into Workspace.
  3. Select your workspace as the root directory. Eclipse will deep-search it and offer all existing projects not already in your workspace as importable. Please check the GeorgGCConnector-project. Uncheck Copy projects into workspace since it’s already in there. Now press Finish.

If you didn’t change your Eclipse settings it will now begin to generate files and build the application. Hopefully there are no compile-errors ;-). If there are, this might be due to Eclipse getting hiccups when suddenly confronted with new projects. Before looking deeper into the problem do a Project-Menu -> Clean-Build. If the problem persists, it may help to wait a few seconds and then do the Build-Clean again (sic!)
When there are no compile-errors, start the application in the same way you started the “Hello, Android”-Sample, just this time we will run the connector on your phone.

  1. On your phone go to the Settings and select Applications. There enable Unknown sources and go to Development. Here enable USB debugging.
  2. Connect your phone to your computer.
  3. If you want to check if the connection works:
    1. Go to the Window-Menu -> Open Perspective -> Other
    2. Choose DDMS-Perspective
    3. In the Devices-View check if your phone is now listed
    4. Return to the Java-Perspective
  4. Select Run-Menu -> Run and Android Application.
  5. Eclipse will have noticed you connected your phone and offer to run the application on your phone.

When you start up the sample application on your phone it automatically registers with GeOrg. If you want to test it, enter a Groundspeak account into the settings. Then start GeOrg and choose the connector at the bottom of the settings page. Now the Find Nearby Page is unlocked. Also in the Map you can now select the connector as the datasource in the Source-Menu.

Content of the sample

The source code has some documentation but here’s a broad overview about how everything is connected:

  • /GeorgGCConnector/AndroidManifest.xml
    The manifest-file contains general information about the application. What to start, which permissions are needed, which icon to use and – very important for the Connector – what content-providers there are.

  • /GeorgGCConnector/res/drawable
    Place a custom icon here and connect it via the AndroidManifest.xml

  • /GeorgGCConnector/res/xml
    Contains the layout for the Connector-Preference-Page. Referenced by GCHttpConnectorSettings.java

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCHttpConnectorSettings.java
    A simple preference-layout that’s also the start-activity if the user starts the Connector. Here the user may enter information the Connector needs to do its work.

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCHttpConnector.java
    This is the Connector-implementation. This class is called when GeOrg requests data from the Connector and it has to decide which action will be taken and which implementation to use. Probably you can reuse this class and just put your own implementation behind it instead of …

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCLoader.java
    The sample’s implementation. Just so that or Connector-Sample doesn’t do nothing.
    This code uses the Groundspeak GoogleMaps-Mashup API to find caches and allows for downloading GPX from their site.

Sample functionality

To give you a feeling about the potential of the Connector-mechanism we decided to provide some functionality in our sample that’s to some extend usable and not just some cheap “Hello GeOrg”-stuff.

It’s basically a connector to the Groundspeak-website. It uses their GoogleMaps-Mashup JSON-Interface to find caches and allows for downloading GPX from the site.

It behaves just like a (very specialised) browser and only connects to Groundspeak upon user-interaction and within a normal traffic-range. Thus it can’t be called a spider, bot or crawler and so might be ok according to Groundspeaks Terms of Use. There is no official statement from Groundspeak though, so use it at your own risk.

Also the interface used here is not officially documented. It may be subject to sudden change or cease to exist altogether. Don’t rely on this code in any way.

Be aware that ranitos don’t distribute this sample as part of GeOrg. Nor do we encourage the use of the sample on your device except as a demonstration of the Connector-mechanism. As to support, we’ll give you support for the basic Connector-mechanism itself but not for the concrete functionality of this sample.

License

The sample code and everything within the connector-sample.zip-archive is public domain. Use it however you wish at your own risk.