Pierwsze kroki z biblioteką klienta Google Data w języku Java

Stephanie Liu, zespół interfejsów API danych Google
Wrzesień 2007 r.
  1. Wprowadzenie
  2. Instalowanie zależności
    1. W systemie Windows
    2. W systemie Mac OS X
    3. W systemie Linux
  3. Instalowanie biblioteki klienta Google Data
  4. Przykłady uruchamiania
  5. Tworzenie własnych aplikacji
  6. Podsumowanie
  7. Dodatek: ustawianie zmiennych środowiskowych

Wprowadzenie

Rozpoczęcie tworzenia aplikacji z użyciem nieznanego interfejsu API nigdy nie jest łatwe, dlatego w tym artykule znajdziesz szczegółowe instrukcje pobierania i instalowania biblioteki klienta interfejsów API danych Google („GData”) dla języka Java. Wyjaśnię, jak uzyskać wszystkie zależności i ustawić potrzebne zmienne środowiskowe. Wkrótce będziesz łączyć różne usługi GData.

Korzystasz z Eclipse?

Przeczytaj artykuł Coding in the Shade: Using Eclipse with Google Data APIs (Kodowanie w cieniu: używanie Eclipse z interfejsami Google Data API).

Instalowanie zależności

Biblioteka klienta GData Java ma te zależności zewnętrzne: W kolejnych sekcjach opisujemy, jak zainstalować te zależności w ulubionym systemie operacyjnym (lub w systemie, którego musisz używać w pracy).

  • JDK (Java Development Kit) w wersji 1.5 lub nowszej
  • Apache Ant w wersji 1.7 lub nowszej
  • mail.jar w Sun's JavaMail API 1.4+
  • activation.jar w Sun's JavaBeansActivationFramework. Jest to wymagane tylko w przypadku interfejsów API związanych z multimediami, takich jak Document List Data API, Picasa Web Album API i YouTube Data API.
  • servlet.jar w Sun's Servlet API w wersji 2.3 lub nowszej. Jest to wymagane tylko w przypadku wykonywania przykładowego kodu w pakietach „sample.authsub” lub „sample.gbase.recipe”.

Niektóre zależności .jar są wymagane tylko w przypadku określonych przykładów, ale aby uniknąć błędów kompilacji, najlepiej pobrać wszystkie. Aby kontynuować, wybierz system operacyjny: Windows, Mac OS X lub Linux.

Instalowanie biblioteki klienta Google Data

  1. Otwórz stronę http://code.google.com/p/gdata-java-client/downloads/list.
  2. Pobierz najnowszą wersję biblioteki klienta (gdata-src.java-1.x.x.java.zip) i przykłady (gdata-samples.java-1.x.x.java.zip).
  3. Rozpakuj źródło biblioteki klienta na komputerze.
  4. Przejdź do pliku gdata/java/build-src/build.properties i otwórz go.
  5. Edytuj zależności zewnętrzne, aby wskazywały lokalizacje plików .jar na komputerze lokalnym.

    6. Uwaga: w systemie Windows pamiętaj, aby używać znaku ucieczki dla ukośników odwrotnych. Na przykład

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

Przykłady uruchomienia

Wszystkie dostępne próbki znajdziesz w archiwum gdata/java/sample w sekcji gdata-samples.java-1.x.x.java.zip. Plik gdata/java/build-samples/build.properties zawiera wszystkie wartości wejściowe dla próbek znajdujących się w bibliotece. Ustaw sample.credentials.username i sample.credentials.password na prawidłową nazwę użytkownika i hasło. Możemy użyć narzędzia Ant do tworzenia i wykonywania próbek.

Sprawdź, czy wszystko zostało prawidłowo zainstalowane. W tym celu otwórz wiersz poleceń, przejdź do katalogu gdata/java i wpisz:

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

Możesz otrzymać informacje lub ostrzeżenia, ale na końcu znajdziesz wiadomość BUILD SUCCESSFUL. Jeśli nie pojawi się komunikat o pomyślnym zakończeniu testu, zapoznaj się z sekcją rozwiązywania problemów.

Aby wypróbować bardziej interaktywny przykład, wpisz:

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

Aby dowiedzieć się, jak uruchomić konkretny przykład, otwórz gdata/java/build-samples i sprawdź plik kompilacji tego przykładu. Znajdź sekcję samples run.

Rozwiązywanie problemów

Jeśli kompilacja się nie powiedzie i pojawi się komunikat o błędzie, np.

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

lub podobny komunikat o błędzie dotyczący braku w projekcie niezbędnego pliku, może to oznaczać, że używasz starszej wersji narzędzia Ant. Wpisz ant -version, aby sprawdzić, czy korzystasz z wersji 1.7 lub nowszej. Aby pobrać najnowszą wersję Ant, postępuj zgodnie z instrukcjami dotyczącymi zależności powyżej.

Tworzenie własnych aplikacji

Kolejne pytanie brzmi: jak utworzyć własną aplikację. Przejdę przez program będący odpowiednikiem „Hello, World!” przy użyciu usługi Kalendarz, aby zademonstrować podstawowe funkcje. Więcej szczegółowych informacji znajdziesz w przewodniku dla deweloperów dotyczącym biblioteki klienta Java oraz w przewodnikach dla deweloperów dotyczących poszczególnych usług.

Utwórz plik o nazwie CalendarTest.java. Zacznij od dodania tych instrukcji importowania.

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.*;

Oto cały program (bez obsługi wyjątków).

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");

Następnie ustawiany jest adres URL zasobu. W tym przypadku możesz poprosić uwierzytelnionego użytkownika o listę wszystkich kalendarzy.

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

Poniższy wiersz wykona polecenie GET na adresie URL i umieści wynikowy plik danych w uporządkowanym obiekcie.

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

Pętla for poniżej będzie iterować po każdym wpisie i wyświetlać tytuł. Pamiętaj, że tytuł jest przechowywany jako TextConstruct, więc aby uzyskać zwykły tekst, musisz wykonać dodatkowe wywołanie funkcji.

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

To było dość proste. Omówmy jeszcze kilka innych typowych kwestii. Z tego fragmentu kodu dowiesz się, jak utworzyć obiekt i go wstawić. W naszym przykładzie będzie to nowe wydarzenie w kalendarzu.

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);

Inną częstą operacją jest tworzenie zapytania.

//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());
}

Podczas debugowania przydatne jest też zrzucanie surowego kodu XML. W bibliotece znajdziesz przydatne narzędzie, które Ci w tym pomoże. Sprawdź, czy plik samples.util.* został zaimportowany. Następnie odrzuć plik danych lub wpis.

CommonUtils.dump(resultFeed, System.out);

Aby uzyskać jeszcze bardziej zaawansowane narzędzia do debugowania, przeczytaj nasz artykuł Debugowanie klientów interfejsu Google Data API: badanie ruchu w programie, w którym znajdziesz informacje o włączaniu rejestrowania w bibliotece klienta.

Dzięki temu dowiesz się, jak wygląda tworzenie aplikacji przy użyciu biblioteki klienta. Więcej informacji znajdziesz w sekcji podsumowania, w której znajdziesz listę dostępnych przewodników dla programistów dotyczących poszczególnych interfejsów Google Data API.

Podsumowanie

Mamy nadzieję, że teraz możesz tworzyć i uruchamiać aplikacje za pomocą biblioteki klienta GData w języku Java. Nie omawiam żadnych popularnych środowisk IDE, ale możesz zapoznać się z popularnymi narzędziami, takimi jak Eclipse czy NetBeans. Oto kilka dodatkowych linków, które mogą Ci się przydać:

Jeśli masz pytania dotyczące korzystania z biblioteki klienta Java z dowolnym interfejsem API, możesz je zadać na forach poświęconych poszczególnym interfejsom API.