Premiers pas avec la bibliothèque cliente Java Google Data

Stephanie Liu, équipe Google Data APIs
Septembre 2007
  1. Introduction
  2. Installer des dépendances
    1. Sous Windows
    2. Sous 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 développer avec une API inconnue. Cet article contient donc des instructions détaillées sur le téléchargement et l'installation de la bibliothèque cliente Java des API Google Data ("GData"). Je vais vous présenter toutes les dépendances et définir les variables d'environnement dont vous aurez besoin. Vous allez 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 (Codage à l'ombre : utiliser Eclipse avec les API Google Data).

Installer les dépendances

La bibliothèque cliente Java GData contient 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 sur le système d'exploitation avec lequel vous êtes bloqué au travail).

  • JDK (Java Development Kit) 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 le fichier JavaBeansActivationFramework de Sun. Cette étape n'est requise que pour les API spécifiques aux médias, y compris l'API Document List Data, l'API Picasa Web Album et l'API YouTube Data.
  • servlet.jar dans la version 2.3 ou plus récente de l'API Servlet Sun. Ce paramètre n'est requis que si vous exécutez des exemples de code dans les packages "sample.authsub" ou "sample.gbase.recipe".

Quelques dépendances .jar ne sont requises que pour des échantillons spécifiques, mais pour éviter les erreurs de compilation, il est préférable d'obtenir toutes les données. Pour continuer, choisissez le système d'exploitation de votre choix : Windows, Mac OS X ou Linux.

Installer la bibliothèque cliente Google Data

  1. Accédez à la page 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 de sorte qu'elles pointent vers les emplacements 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 à partir de 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 exemples 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 créer 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, puis saisissez:

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

Vous pouvez recevoir des informations ou des messages d'avertissement, mais il vous suffit de rechercher le message BUILD SUCCESSFUL à la fin : Si aucun message de confirmation ne s'affiche, consultez la section de dépannage.

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 correspondant à cet exemple. Recherchez la section samples run.

Dépannage

Si la compilation échoue et affiche 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 similaire concernant un fichier essentiel manquant dans le projet, vous utilisez peut-être une ancienne version d'Ant. Saisissez ant -version pour vous assurer que vous utilisez la version 1.7 ou une version ultérieure. Reportez-vous aux instructions de dépendance 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 suivre un programme équivalent "Hello World!" 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 des développeurs spécifiques au 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 l'ensemble du programme (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, vous pouvez demander à obtenir 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écute la commande GET sur l'URL et place le flux résultant dans un objet bien rangé.

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

La boucle for ci-dessous parcourt chaque entrée et imprime 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 simple, passons à d'autres exemples courants. L'extrait de code 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);

Une autre opération courante consiste à créer une requête.

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

Pendant le débogage, une autre opération utile consiste à vider le fichier XML brut. Il existe un utilitaire pratique que vous pouvez utiliser dans la bibliothèque. Assurez-vous que samples.util.* est importé. puis videz le flux ou l'entrée.

CommonUtils.dump(resultFeed, System.out);

Pour des outils de débogage encore plus détaillés, consultez notre article Déboguer les clients API Google Data: explorer le trafic depuis votre programme sur la façon d'activer la journalisation depuis la bibliothèque cliente.

Vous aurez ainsi une idée de ce à quoi ressemble la création d'applications à l'aide de la bibliothèque cliente. Pour en savoir plus, consultez la section sur la conclusion afin d'obtenir la liste des guides du développeur disponibles pour chaque API Google Data.

Conclusion

Nous espérons que vous êtes désormais en mesure de créer et d'exécuter des applications à l'aide de la bibliothèque cliente Java GData. Je n'ai pas utilisé les IDE les plus populaires, mais vous pouvez vous intéresser aux outils populaires comme Eclipse ou NetBeans. Voici quelques liens supplémentaires qui pourraient vous être utiles:

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