Erste Schritte mit der Google Data-Java-Clientbibliothek

Stephanie Liu, Google Data APIs-Team
September 2007
  1. Einführung
  2. Abhängigkeiten installieren
    1. Unter Windows
    2. Unter Mac OS X
    3. Unter Linux
  3. Google Data-Clientbibliothek installieren
  4. Beispiele ausführen
  5. Eigene Anwendungen erstellen
  6. Schlusswort
  7. Anhang: Umgebungsvariablen festlegen

Einführung

Es ist nie ganz einfach, mit einer unbekannten API zu entwickeln. Deshalb gibt es in diesem Artikel eine detaillierte Anleitung zum Herunterladen und Installieren der Java-Clientbibliothek für die Google Data APIs („GData“). Ich werde alle Abhängigkeiten abrufen und die erforderlichen Umgebungsvariablen festlegen. Sie erstellen im Handumdrehen verschiedene GData-Dienste.

Verwenden Sie Eclipse?

Lesen Sie den Artikel Coding in the Shade: Using Eclipse with Google Data APIs.

Abhängigkeiten installieren

Für die GData-Java-Clientbibliothek gelten die folgenden externen Abhängigkeiten. In den folgenden Abschnitten wird beschrieben, wie Sie diese Abhängigkeiten auf Ihrem bevorzugten Betriebssystem (oder dem Betriebssystem, auf dem Sie bei der Arbeit stecken) installieren.

  • JDK (Java Development Kit) Version 1.5 und höher
  • Apache Ant Version 1.7+
  • mail.jar in der JavaMail API ab Version 1.4 von Sun
  • activation.jar im JavaBeansActivationFramework von Sun. Dies ist nur für medienspezifische APIs erforderlich, darunter die Document List Data API, die Picasa Web Album API und die YouTube Data API.
  • Servlet.jar in Version 2.3 oder höher der Sun Servlet API. Dies ist nur erforderlich, wenn Sie Codebeispiele in "sample.authsub"- oder "sample.gbase.recipe"-Paketen ausführen.

Einige .jar-Abhängigkeiten sind nur für bestimmte Beispiele erforderlich. Damit Build-Fehler vermieden werden, sollten Sie jedoch einfach alles abrufen. Wählen Sie das gewünschte Betriebssystem aus, um fortzufahren: Windows, Mac OS X oder Linux.

Google Data-Clientbibliothek installieren

  1. Rufen Sie http://code.google.com/p/gdata-java-client/downloads/list auf.
  2. Laden Sie die neueste Version der Clientbibliothek (gdata-src.java-1.x.x.java.zip) und die Beispiele (gdata-samples.java-1.x.x.java.zip) herunter.
  3. Extrahieren Sie die Clientbibliotheksquelle auf Ihren Computer.
  4. Gehen Sie zu gdata/java/build-src/build.properties und öffnen Sie die Datei.
  5. Bearbeiten Sie die externen Abhängigkeiten, um auf die Speicherorte der .jar-Dateien auf Ihrem lokalen Computer zu verweisen.

    6. Hinweis: Unter Windows müssen Sie die umgekehrten Schrägstriche maskieren. Beispiel:

    servlet.jar=C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0\\lib\\servlet-api.jar

Beispiele ausführen

Alle verfügbaren Stichproben befinden sich im Archiv gdata-samples.java-1.x.x.java.zip unter gdata/java/sample. Die Datei gdata/java/build-samples/build.properties enthält alle Eingabewerte für die Beispiele in der Bibliothek. Legen Sie sample.credentials.username und sample.credentials.password auf einen gültigen Nutzernamen und ein gültiges Passwort fest. Mit Ant können wir die Beispiele erstellen und ausführen.

Testen Sie, ob Sie alles korrekt installiert haben. Öffnen Sie dazu die Eingabeaufforderung, wechseln Sie in das Verzeichnis gdata/java und geben Sie Folgendes ein:

ant -f build-samples.xml sample.calendar.run

Möglicherweise erhalten Sie einige Informationen oder Warnmeldungen. Achten Sie aber auf die BUILD SUCCESSFUL-Meldung am Ende. Wenn Sie keine Erfolgsmeldung erhalten, lesen Sie den Abschnitt Fehlerbehebung.

Probieren Sie ein interaktiveres Beispiel aus, indem Sie Folgendes eingeben:

ant -f build-samples.xml sample.spreadsheet.guidemo.run

Wenn Sie wissen möchten, wie Sie ein bestimmtes Beispiel ausführen, rufen Sie gdata/java/build-samples auf und prüfen die Build-Datei für dieses Beispiel. Suchen Sie nach dem Abschnitt samples run.

Fehlerbehebung

Wenn Ihr Build mit einer Fehlermeldung wie

BUILD FAILED
Target 'core.sample.core.util.build' does not exist in this project. It is used from target 'sample.calendar.build'.

Total time: 0 seconds

oder eine ähnliche Fehlermeldung zu einer wichtigen Datei, die im Projekt fehlt, verwenden Sie möglicherweise eine ältere Version von Ant. Geben Sie ant -version ein, um Version 1.7 oder höher auszuführen. In der Anleitung zu Abhängigkeiten oben finden Sie die aktuelle Version von Ant.

Eigene Anwendungen erstellen

Die nächste Frage ist, wie Sie Ihre eigene Anwendung erstellen. Ich werde ein „Hello World!“-Äquivalentprogramm mit dem Kalenderdienst durcharbeiten, um grundlegende Funktionen zu demonstrieren. Ausführliche Informationen finden Sie im Entwicklerleitfaden zur Java-Clientbibliothek sowie in den einzelnen Entwicklerleitfäden für Produkte.

Erstellen Sie eine Datei namens CalendarTest.java. Nehmen Sie zuerst die folgenden Importanweisungen auf.

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.calendar.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;

import java.net.*;
import java.io.*;

import sample.util.*;

Hier ist das gesamte Programm (ohne Ausnahmen).

public class CalendarTest {

    public static void main(String[] args) {
        CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
        myService.setUserCredentials("root@gmail.com", "pa$$word");

        URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");
        CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

        System.out.println("Your calendars:");
        System.out.println();

        for (int i = 0; i < resultFeed.getEntries().size(); i++) {
          CalendarEntry entry = resultFeed.getEntries().get(i);
          System.out.println("\t" + entry.getTitle().getPlainText());
        }

    }
}

This little program will request all the calendars you own and display all the titles. It's a little longer than the canonical "Hello, World!" example, but it's very simple once we break it down. The first couple of lines creates a service object and sets the user credentials.

CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
myService.setUserCredentials("root@gmail.com", "pa$$word");

Dann wird die URL der Ressource festgelegt. In diesem Fall können Sie die Liste aller Kalender vom authentifizierten Nutzer anfordern.

URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");

Mit der Zeile unten wird der Befehl GET für die URL ausgeführt und der daraus resultierende Feed in ein aufgeräumtes Objekt eingefügt.

CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

Die folgende for-Schleife durchläuft jeden Eintrag und gibt den Titel aus. Der Titel wird als TextConstruct gespeichert. Ein zusätzlicher Funktionsaufruf ist erforderlich, um den Nur-Text-Text zu erhalten.

for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    CalendarEntry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
}

Das war ziemlich einfach – sehen wir uns einige andere Dinge an. Im folgenden Snippet sehen Sie, wie Sie ein Objekt erstellen und einfügen. In unserem Beispiel ist das ein neuer Eintrag für einen Kalendertermin.

URL postURL = new URL("http://www.google.com/calendar/feeds/root@gmail.com/private/full");
CalendarEventEntry myEvent = new CalendarEventEntry();

//Set the title and description
myEvent.setTitle(new PlainTextConstruct("Pi Day Party"));
myEvent.setContent(new PlainTextConstruct("I am throwing a Pi Day Party!"));

//Create DateTime events and create a When object to hold them, then add
//the When event to the event
DateTime startTime = DateTime.parseDateTime("2007-03-14T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2007-03-14T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEvent.addTime(eventTimes);

// POST the request and receive the response:
CalendarEventEntry insertedEntry = myService.insert(postURL, myEvent);

Ein weiterer häufiger Vorgang ist das Erstellen einer Abfrage.

//Create a new query object and set the parameters
Query myQuery = new Query(feedURL);
myQuery.setFullTextQuery("Pi");

//Send the request with the built query URL
CalendarEventFeed myResultsFeed = myService.query(myQuery, CalendarEventFeed.class);

//Take the first match and print the title
if (myResultsFeed.getEntries().size() > 0) {
    CalendarEventEntry firstMatchEntry = new CalendarEventEntry();
    myResultsFeed.getEntries().get(0);
    System.out.println(firstMatchEntry.getTitle().getPlainText());
}

Während der Fehlerbehebung ist es ein weiterer nützlicher Vorgang, die Roh-XML auszugeben. In der Bibliothek ist dafür ein praktisches Dienstprogramm verfügbar. samples.util.* muss importiert werden. Sichern Sie dann den Feed oder Eintrag.

CommonUtils.dump(resultFeed, System.out);

Noch ausführlichere Debugging-Tools finden Sie im Artikel Debugging von Google Data API-Clients: Untersuchen innerhalb Ihres Programms.

So können Sie sich einen Eindruck davon verschaffen, wie das Erstellen von Anwendungen mit der Clientbibliothek ist. Weitere Informationen finden Sie im Abschnitt zur Schlussfolgerung. Dort finden Sie eine Liste der verfügbaren Entwicklerleitfäden für die einzelnen Google Data APIs.

Fazit

Wir hoffen, dass Sie jetzt mit der GData-Java-Clientbibliothek Anwendungen erstellen und ausführen können. Ich habe mir keine der gängigen IDEs angesehen, aber du kannst dir auch beliebte Tools wie Eclipse oder NetBeans ansehen. Hier sind einige zusätzliche Links, die hilfreich sein könnten:

Wenn Sie Fragen zur Verwendung der Java-Clientbibliothek mit einer beliebigen API haben, können Sie sich in den API-spezifischen Foren an uns wenden.