Entwickler: Eigenen Connector implementieren

GeOrg kann Cache-Daten aus externen Datenquellen in Echtzeit anzeigen (z.B. von Webseiten, Datenbanken, etc). Dabei geht es hauptsächlich um die Anzeige auf der Map-Page und der Find Nearby-Page. Das ist besonders nützlich, wenn Du spontan cachen möchtest und keine GPX-Datei zum Importieren vorbereitet hast.

Diese externen Datenquellen werden GeOrg über einen Mechanismus bereitgestellt, den wir “Connector” nennen. Connectoren werden als Android Content Provider implementiert und können sich nach dem Start bei einer bestehenden GeOrg-Installation registrieren. Ein solcher Connector muss nur ein paar Queries bereitstellen, um GeOrg mit Daten versorgen zu können.

Damit Ihr loslegen könnt, findet Ihr hier den Sourcecode eines Beispiel-Connectors zum Download (Version: 1.0.9), der eine vollständige Implementierung der Queries beinhaltet. Als Beispielimplementierung haben wir Anfragen gegen die Schnittstellte des GoogleMaps-Mashups von Groundspeak gewählt. Das Zip-File enthält ein komplettes Eclipse-Projekt, dass Du auf Deinem Rechner kompilieren kannst und sofort auf Dein Android-Handy hochladen kannst. Du könntest es auch im Emulator testen, aber da Du dort ja keinen GeOrg hast, um es aufzurufen, ist das vielleicht eher zum Testen und Debuggen gut. Falls Du mit der Android-Entwicklung noch nicht vertraut bist, im folgenden eine kurze Einführung mit dem Connector im Fokus:

Konzept

Ein Connector liefert Daten, die von GeOrg hauptsächlich auf Map- und auf der Find-Nearby-Page angezeigt werden. Die Kommunikation läuft über einen Android-spezifischen Mechanismus namens “Content Provider”. Kurz gesagt schickt GeOrg einen Request an einen URI, auf dem sich er Connector registriert hat. Dieser empfängt den Request, analysiert die Parameter und entscheidet, wie der Request zu behandeln ist. Das Ergebnis wird dann GeOrg mittels eines MatrixCursors zurückgegeben, der sowas ist wie ein SQL-Cursor, nur ohne Datenbank dahinter.

Damit GeOrg den URI des Connectors kennt, muss sich der Connector bei GeOrg registriert haben. In der Registrierungsanfrage (auch ein Request an einen Content Provider) übergibt der Connector seinen URI und GeOrg prüft mit einem Rückrequest, ob der Connector auch unter diesem URI erreichbar ist.
Das Beispiel tut das jedesmal, wenn die Beispiel-App gestartet wird. Dies muss der Benutzer ohnehin tun, um einige Einstellungen zu setzen. Ein Connector kann sich also beliebig oft an GeOrg registrieren, er muss nur stets denselben URI verwenden.

Zur Zeit muss ein vollständiger Connector vier verschiedene Aktionen / Queries unterstützen. Es empfiehlt sich, auch wenn nicht alle Aktionen unterstützt werden, wenigstens eine leere Liste zurückzugeben oder einen Fehler zurückzumelden. Es handelt sich um folgende Aktionen:

  • cacheByCoord – Muss Caches innerhalb eines geographischen Recktecks zurückliefern
  • cacheDetails – Muss zusätzliche Daten zu einzelnen Caches aus dem ResultSet von cacheByCoord() liefern können.
  • readGPX – Muss GPX-Daten zu einem Cache liefern können, der mittels des GC-Codes angefragt wird.
  • ping – Muss “OK” zurückliefern und wird von GeOrg verwendet, um den URI des Connectors auf Gültigkeit zu prüfen.

Empfohlene Lektüre

Was die Android-Entwicklung angeht, so gibt es eine Unmenge an Informationen auf http://developer.android.com. Am wichtigsten sind dabei der Developer Guide und als Nachschlagewerk die Reference.

Wenn Du mit Android noch nie etwas gemacht hast, fängst Du am besten so an:

  1. Downloade und installiere die Eclipse IDE for Java Developers.
  2. Downloade und installiere das Android 1.6 SDK und das Android Plugin für Eclipse (ADT). Der Link enthält beides.
  3. Starte Eclipse und lege einen Workspace für Deine Android Projekte irgendwo auf Deiner Platte an. Eclipse fragt Dich beim ersten Start, wo es den Workspace anlegen soll.
  4. Schaue Dir das Hello, Android-Sample an und gehe die einzelnen Schritte dort durch. Das zeigt Dir ein wenig vom Umgang mit Eclipse, wie man Android Projekte aufsetzt und wie man den Emulator startet.
  5. Falls Du einen “.class compatibility”-Fehler bekommst, musst Du sicherstellen, dass der JDK1.5-Compiler voreingestellt ist. Das machst Du so:
    Window-Menü -> Preferences -> Java -> Compiler -> Compiler compliance level. Setze hier den Wert auf “1.5”.

Connector-Beispiel zum Laufen bringen

Ok, Du hast das Connector-Beispiel heruntergeladen und “Hello, Android” läuft bei Dir. Wie öffnest Du jetzt das Beispiel-Projekt?

  1. Entpacke die Datei connector-sample.zip, die Du heruntergeladen hast, in ein neues Verzeichnis Deines Workspace-Verzeichnissen. Stelle sicher, dass beim Entpacken die im Zip-File vorhandene Verzeichnisstruktur erhalten bleibt.
  2. In Eclipse wähle File-Menü -> Import and aus dem Dialog dann General -> Existing Projects into Workspace.
  3. Wähle nun Deinen Workspace als root-Verzeichnis. Eclipse führt nun eine rekursive Suche in diesem Verzeichnis durch und wird dir alle vorhandenen Projekte in diesem Verzeichnis, die noch nicht in Deiner Workspace-Struktur angezeigt werden, zum Import anbieten. Wähle hier das GeorgGCConnector-Projekt aus. Den Haken Copy projects into workspace solltest Du abschalten, da das Projekt ja schon im Workspace-Verzeichnis liegt. Nun drückst Du Finish.

Falls Du nichts an den Standard-Eclipse-Einstellungen geändert hast, wird es nun beginnen, das Projekt zu kompilieren und die für die App notwendigen Dateien zu erzeugen. Hoffentlich gibt es keine Compile-Fehler :-). Falls doch, könnte das daran liegen, dass Eclipse mit Android Plugin manchmal etwas irritiert reagiert, wenn man es mit brandneuen Projekten konfrontiert. Bevor Du also Zeit in die Analyse der Fehler steckst, solltest Du mal versuchen, es durch einen “Build Clean” (Project-Menu -> Clean) zu lösen. Falls das Problem immer noch existiert, kann es auch helfen, ein paar Sekunden zu warten und den “Build Clean” noch einmal auszulösen (echt wahr!)
Wenn es keine Compile-Fehler gibt, starte die Anwendung genauso, wie Du die “Hello, Android”-Anwendung gestartet hast, allerdings werden wir diesmal die Anwendung nicht im Emulator sondern auf Deinem Handy laufen lassen:

  1. Gehe auf Deinem Handy in die Einstellungen und wähle Anwendungen. Dort aktiviere Unbekannte Quellen und gehe dann unter Entwicklung. Dort aktivierst Du USB debugging.
  2. Verbinde Dein Handy mit Deinem Computer.
  3. Wenn Du sehen möchtest, ob die Verbindung funktioniert:
    1. Gehe ins Window-Menü -> Open Perspective -> Other
    2. Wähle DDMS-Perspective
    3. Schau, ob in der Devices-View nun Dein Handy gelistet ist
    4. Gehe zurück zur Java-Perspective
  4. Wähle im Run-Menu -> Run und dann Android Application.
  5. Eclipse sollte Dir nun, da es Dein Handy erkannt hat, anbieten, die Anwendung auf Dein Handy zu installieren.

Wenn Die Anwendung auf Deinem Handy installiert ist und Du sie startest, registriert sie sich erst einmal bei GeOrg. Möchtest Du die Funktionalität testen, kannst Du in der Anwendung Deinen Groundspeak-Account eingeben. Danach startest Du GeOrg und wählst den Connector unten auf der Settings-Page. Nun ist die Find-Nearby-Seite freigeschaltet. Außerdem kannst Du den Connector auf der Map-Page über das Source-Menü auswählen.

Inhalt des Beispiels

Der Sourcecode enthält einiges an Dokumentation, hier daher ein grober Überblick, wie alles zusammenspielt:

  • /GeorgGCConnector/AndroidManifest.xml
    Die manifest-Datei enthält generelle Informationen zur App. Was genau gestartet wird, welche Berechtigungen benötigt werden (zB Internet-Zugriff), welches Icon verwendet wird und – wichtig für den Connector – ob es Content-Provider gibt und welche das sind.

  • /GeorgGCConnector/res/drawable
    Hier könntest Du ein eigenes Icon ablegen und es in der AndroidManifest.xml referenzieren.

  • /GeorgGCConnector/res/xml
    Hier liegt das Bildschirm-Layout für die Connector-Preference-Page. Sie wird von der GCHttpConnectorSettings.java referenziert.

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCHttpConnectorSettings.java
    Eine einfache Preference-Activity, die angezeigt wird, wenn der Benutzer den Connector startet. Hier kann man Daten eingeben, die der Connector für seine Aufgabe benötigt.

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCHttpConnector.java
    Dies ist die Content-Provider-Implementierung. Hier werden die unterschiedlichen Queries unterschieden, die Parameter ausgelesen und dann die eigentliche Datenbeschaffungslogik aufgerufen. Vermutlich kannst Du diese Klasse 1:1 für Deine eigene Implementierung weiterbenutzen und nur die aufgerufenen Methoden neu implementieren, anstatt der …

  • /GeorgGCConnector/src/org/example/georg/connector/gc/GCLoader.java
    … Beispiel-Logik. In diesem Beispiel nur vorhanden, damit der Connector nicht nichts macht. Der Code verwendet das GoogleMaps-Mashup von Groundspeak um Caches zu finden und lädt einzelne GPX-Files auf User-Request von der Seite, so als ob man manuell den GPX-Knopf in einem Cachelisting betätigt hätte.

Beispiel-Funktionalität

Um Dir ein Gefühl für das Potential des Connector-Mechanismus zu geben, haben wir uns entschieden, nicht nur ein einfaches “Hello GeOrg”-Beispiel zu bauen, sondern etwas, was auch vernünftige Ergebnisse liefert und als Basis für eigene Implementierungen dienen kann.

Es handelt sich einfach gesagt um einen Connector für die Groundspeak-Webseite. Er verwendet das JSON-Interface (das auch für das Geocaching-GoogleMaps-Mashup verwendet wird) um Caches zu finden und kann einzelne GPX-Dateien von der Webseite laden (Natürlich nur, wenn Du Premium Member bist).

Er verhält sich im Prinzip wie ein (sehr spezialisierter) Browser und verbindet sich nur zu Groundspeak, wenn dies durch eine Benutzer-Interaktion ausgelöst wird und innerhalb eines normalen Netzwerk-Verkehrsvolumen. Daher halten wir ihn nicht für die in den Groundspeak Terms of Use ausgeschlossenen Spiders, Bots, oder Crawler und sind der Meinung, dass er Terms of Use-konform ist. Leider gibt es diesbezüglich immer noch kein offizielles Statement von Groundspeak, daher erfolgt die Benutzung auf eigenes Risiko.

Auch ist die Schnittstelle, die hier benutzt wird, nicht offiziell dokumentiert und freigegeben. Sie kann sich plötzlich ändern oder nicht mehr verfügbar sein. Verlass Dich daher nicht auf diesen Beispiel-Code!

Nimm bitte auch zur Kenntniss, dass dieses Beispiel nicht Teil von GeOrg ist. Wir empfehlen nicht, den Beispiel-Code auf Deinem Handy oder im Emulator zu benutzen außer als Beispiel für die Connector-Architektur. Bezüglich Support – wir übernehmen Support für den grundsätzlichen Connector-Mechanismus aber nicht für die konkrete Funktionalität dieses Beispiels.

Lizenz

Der Beispiel-Code und alles im connector-sample.zip-archive ist public domain. Nutze es, wie Du es für richtig hältst und auf eigenes Risiko.