Introduzione alla libreria client Java di Google Data

Stephanie Liu, team delle API Google Data
Settembre 2007
  1. Introduzione
  2. Installazione delle dipendenze
    1. Su Windows
    2. Su Mac OS X
    3. In Linux
  3. Installazione della libreria client Google Data
  4. Campioni di corsa
  5. Creare le proprie applicazioni
  6. Conclusione
  7. Appendice: impostazione delle variabili di ambiente

Introduzione

Non è mai facile iniziare a sviluppare con un'API sconosciuta, quindi questo articolo fornisce istruzioni passo passo su come scaricare e installare la libreria client Java delle API Google Data ("GData"). Vedremo come ottenere tutte le dipendenze e impostare le variabili di ambiente necessarie. In men che non si dica, potrai combinare diversi servizi GData.

Utilizzi Eclipse?

Consulta l'articolo Coding in the Shade: Using Eclipse with Google Data APIs.

Installazione delle dipendenze

La libreria client Java GData ha le seguenti dipendenze esterne. Le sezioni seguenti descrivono come installare queste dipendenze sul tuo sistema operativo preferito (o su quello che usi al lavoro).

  • JDK (Java Development Kit) versione 1.5 o successive
  • Apache Ant versione 1.7 o successive
  • mail.jar nell'API JavaMail 1.4+ di Sun
  • activation.jar in JavaBeansActivationFramework di Sun. Questo è necessario solo per le API specifiche per i contenuti multimediali, tra cui l'API Document List Data, l'API Picasa Web Album e l'API YouTube Data.
  • servlet.jar nell'API Servlet di Sun versione 2.3 o successive. Questo è necessario solo se si eseguono esempi di codice nei pacchetti "sample.authsub" o "sample.gbase.recipe".

Alcune dipendenze di .jar sono richieste solo per campioni specifici, ma per evitare errori di compilazione, è meglio scaricare tutto. Scegli il sistema operativo che preferisci per continuare: Windows, Mac OS X o Linux.

Installazione della libreria client Google Data

  1. Visita http://code.google.com/p/gdata-java-client/downloads/list.
  2. Scarica l'ultima versione della libreria client (gdata-src.java-1.x.x.java.zip) e degli esempi (gdata-samples.java-1.x.x.java.zip).
  3. Estrai l'origine della libreria client sul computer.
  4. Vai a gdata/java/build-src/build.properties e apri il file.
  5. Modifica le dipendenze esterne in modo che puntino alle posizioni dei file .jar sulla tua macchina locale.

    6. Nota:su Windows, assicurati di eseguire l'escape delle barre rovesciate. Ad esempio,

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

Esecuzione di campioni

Tutti i campioni disponibili si trovano nella cartella gdata/java/sample dell'archivio gdata-samples.java-1.x.x.java.zip. Il file gdata/java/build-samples/build.properties contiene tutti i valori di input per i campioni contenuti nella raccolta. Imposta sample.credentials.username e sample.credentials.password su un nome utente e una password validi. Possiamo utilizzare Ant per compilare ed eseguire gli esempi.

Verifica di aver installato tutto correttamente aprendo un prompt dei comandi, passando alla directory gdata/java e digitando:

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

Potresti ricevere alcune informazioni o messaggi di avviso, ma cerca il messaggio BUILD SUCCESSFUL alla fine. Se non ricevi un messaggio di conferma, consulta la sezione Risoluzione dei problemi.

Prova un esempio più interattivo digitando:

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

Per scoprire come eseguire un particolare esempio, vai a gdata/java/build-samples e controlla il file di build per quell'esempio. Cerca la sezione samples run.

Risoluzione dei problemi

Se la build non va a buon fine e viene visualizzato un messaggio di errore simile a:

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

o un messaggio di errore simile relativo a un file essenziale mancante nel progetto, potresti utilizzare una versione precedente di Ant. Digita ant -version per assicurarti di utilizzare la versione 1.7 o successive. Consulta le istruzioni relative alla dipendenza riportate sopra per scaricare l'ultima versione di Ant.

Creare le proprie applicazioni

La domanda successiva è come creare la tua applicazione. Esaminerò un programma equivalente a "Hello, World!" utilizzando il servizio Calendar per mostrare le funzionalità di base. Per informazioni più dettagliate, consulta la guida per gli sviluppatori della libreria client Java e le guide per gli sviluppatori dei singoli prodotti.

Crea un file denominato CalendarTest.java. Inizia includendo le seguenti istruzioni di importazione.

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

Ecco l'intero programma (senza gestione delle eccezioni).

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

A questo punto, l'URL della risorsa è impostato. In questo caso, è qui che puoi richiedere l'elenco di tutti i calendari dell'utente autenticato.

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

La riga seguente eseguirà il comando GET effettivo sull'URL e inserirà il feed risultante in un oggetto ordinato.

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

Il ciclo for riportato di seguito scorrerà ogni voce e stamperà il titolo. Tieni presente che il titolo viene memorizzato come TextConstruct, quindi è necessaria una chiamata di funzione aggiuntiva per ottenere il testo normale.

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

Questi erano i passaggi di base. Vediamo altre cose comuni. Il seguente snippet mostra come creare un oggetto e inserirlo. Per il nostro esempio, sarà una nuova voce di evento del calendario.

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

Un'altra operazione comune è la creazione di una query.

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

Durante il debug, un'altra operazione utile è l'estrazione dell'XML non elaborato. Esiste un'utilità pratica che puoi utilizzare per farlo nella libreria. Assicurati che samples.util.* sia importato. Poi, scarica il feed o la voce.

CommonUtils.dump(resultFeed, System.out);

Per strumenti di debug ancora più approfonditi, consulta l'articolo Debugging dei client API Google Data: esplorare il traffico dall'interno del programma su come attivare la registrazione dalla libreria client.

In questo modo, potrai farti un'idea di come creare app utilizzando la libreria client. Per informazioni più dettagliate, consulta la sezione Conclusione per un elenco delle guide per gli sviluppatori disponibili per ogni API Google Data.

Conclusione

A questo punto, dovresti essere in grado di creare ed eseguire applicazioni utilizzando la libreria client Java GData. Non ho parlato di nessuno degli IDE più diffusi che puoi utilizzare, ma ti consiglio di dare un'occhiata a strumenti popolari come Eclipse o NetBeans. Ecco alcuni link aggiuntivi che potrebbero esserti utili:

Se hai domande sull'utilizzo della libreria client Java con qualsiasi API, puoi comunicarcelo pubblicando un post nei forum specifici per le API.