Premiers pas avec la bibliothèque cliente Java Google Data

Stephanie Liu, équipe des API Google Data
septembre 2007
  1. Introduction
  2. Installer les dépendances
    1. Sur Windows
    2. Sur Mac OS X
    3. Sous Linux
  3. Installer la bibliothèque cliente Google Data
  4. Exécuter des exemples
  5. Créer vos propres applications
  6. Conclusion
  7. Annexe : Définir des variables d'environnement

Introduction

Il n'est jamais facile de commencer à développer avec une API inconnue. Cet article vous explique donc comment télécharger et installer la bibliothèque cliente Java des API Google Data ("GData"). Je vais vous expliquer comment obtenir toutes les dépendances et définir les variables d'environnement dont vous aurez besoin. Vous pourrez combiner différents services GData en un rien de temps !

Vous utilisez Eclipse ?

Consultez l'article Coding in the Shade: Using Eclipse with Google Data APIs (Coder à l'ombre : utiliser Eclipse avec les API Google Data).

Installer les dépendances

La bibliothèque cliente Java GData présente les dépendances externes suivantes. Les sections suivantes décrivent comment installer ces dépendances sur votre système d'exploitation préféré (ou celui que vous êtes obligé d'utiliser au travail).

  • JDK (kit de développement Java) version 1.5 ou ultérieure
  • Apache Ant version 1.7 ou ultérieure
  • mail.jar dans l'API JavaMail 1.4+ de Sun
  • activation.jar dans JavaBeansActivationFramework de Sun. Cette étape n'est requise que pour les API spécifiques aux contenus multimédias, y compris l'API Document List Data, l'API Picasa Albums Web et l'API YouTube Data.
  • servlet.jar dans l'API Servlet de Sun version 2.3 ou ultérieure. Cette opération n'est requise que si vous exécutez des exemples de code dans les packages "sample.authsub" ou "sample.gbase.recipe".

Certaines dépendances .jar ne sont requises que pour des exemples spécifiques, mais pour éviter les erreurs de compilation, il est préférable de tout obtenir. Choisissez votre système d'exploitation pour continuer : Windows, Mac OS X ou Linux.

Installer la bibliothèque cliente Google Data

  1. Accédez à http://code.google.com/p/gdata-java-client/downloads/list.
  2. Téléchargez la dernière version de la bibliothèque cliente (gdata-src.java-1.x.x.java.zip) et des exemples (gdata-samples.java-1.x.x.java.zip).
  3. Extrayez la source de la bibliothèque cliente sur votre ordinateur.
  4. Accédez à gdata/java/build-src/build.properties et ouvrez le fichier.
  5. Modifiez les dépendances externes pour qu'elles pointent vers l'emplacement des fichiers .jar sur votre ordinateur local.

    6. Remarque : Sous Windows, veillez à échapper les barres obliques inverses. Par exemple,

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

Exécuter des exemples

Tous les exemples disponibles se trouvent sous gdata/java/sample dans l'archive gdata-samples.java-1.x.x.java.zip. Le fichier gdata/java/build-samples/build.properties contient toutes les valeurs d'entrée des échantillons contenus dans la bibliothèque. Définissez sample.credentials.username et sample.credentials.password sur un nom d'utilisateur et un mot de passe valides. Nous pouvons utiliser Ant pour compiler et exécuter les exemples.

Pour vérifier que vous avez tout installé correctement, ouvrez une invite de commande, accédez au répertoire gdata/java et saisissez :

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

Vous pouvez recevoir des messages d'information ou d'avertissement, mais recherchez simplement le message BUILD SUCCESSFUL à la fin. Consultez la section de dépannage si vous ne recevez pas de message de réussite.

Essayez un exemple plus interactif en saisissant :

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

Pour savoir comment exécuter un exemple particulier, accédez à gdata/java/build-samples et consultez le fichier de compilation de cet exemple. Recherchez la section samples run.

Dépannage

Si votre compilation échoue avec un message d'erreur du type

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

ou un message d'erreur semblable indiquant qu'un fichier essentiel est manquant dans le projet, il est possible que vous utilisiez une ancienne version d'Ant. Saisissez ant -version pour vérifier que vous exécutez la version 1.7 ou une version ultérieure. Reportez-vous aux instructions sur les dépendances ci-dessus pour obtenir la dernière version d'Ant.

Créer vos propres applications

La question suivante est de savoir comment créer votre propre application. Je vais passer en revue un programme équivalent à "Hello, World!" en utilisant le service Agenda pour présenter les fonctionnalités de base. Pour en savoir plus, consultez le guide du développeur de la bibliothèque cliente Java, ainsi que les guides du développeur pour chaque produit.

Créez un fichier appelé CalendarTest.java. Commencez par inclure les instructions d'importation suivantes.

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

Voici le programme complet (sans gestion des exceptions).

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

L'URL de la ressource est ensuite définie. Dans ce cas, c'est ici que vous pouvez demander la liste de tous les agendas de l'utilisateur authentifié.

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

La ligne ci-dessous exécutera la commande GET sur l'URL et placera le flux résultant dans un objet ordonné.

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

La boucle for ci-dessous itérera sur chaque entrée et imprimera le titre. Notez que le titre est stocké en tant que TextConstruct. Un appel de fonction supplémentaire est donc nécessaire pour obtenir le texte brut.

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

C'était assez basique. Voyons quelques autres éléments courants. L'extrait suivant vous montre comment créer un objet et l'insérer. Dans notre exemple, il s'agit d'une nouvelle entrée d'événement d'agenda.

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

La création d'une requête est une autre opération courante.

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

Lors du débogage, une autre opération utile consiste à vider le fichier XML brut. La bibliothèque propose un utilitaire pratique pour effectuer cette opération. Assurez-vous que samples.util.* est importé. Ensuite, videz le flux ou l'entrée.

CommonUtils.dump(resultFeed, System.out);

Pour des outils de débogage encore plus approfondis, consultez notre article Déboguer les clients des API Google Data : explorer le trafic depuis votre programme pour savoir comment activer la journalisation depuis la bibliothèque cliente.

Cela devrait vous donner une idée de ce que représente la création d'applications à l'aide de la bibliothèque cliente. Pour en savoir plus, consultez la section Conclusion pour obtenir la liste des guides du développeur disponibles pour chaque API Google Data.

Conclusion

Nous espérons que vous êtes maintenant en mesure de créer et d'exécuter des applications à l'aide de la bibliothèque cliente Java GData. Je n'ai pas abordé les IDE populaires que vous pouvez utiliser, mais vous pouvez consulter des outils populaires tels qu'Eclipse ou NetBeans. Voici quelques liens supplémentaires qui peuvent vous être utiles :

Si vous avez des questions sur l'utilisation de la bibliothèque cliente Java avec une API, vous pouvez nous les poser en publiant un message sur les forums spécifiques à l'API.