Introduzione alla libreria client Java di Google Data

Stephanie Liu, team Google Data API
settembre 2007
  1. Introduzione
  2. Installazione delle dipendenze
    1. Su Windows
    2. Su Mac OS X
    3. In Linux
  3. Installare la libreria client di dati di Google
  4. Campioni in esecuzione
  5. Sviluppa le tue applicazioni
  6. Conclusione
  7. Appendice: impostare le variabili di ambiente

Introduzione

Non è mai facile iniziare a sviluppare con un'API sconosciuta, quindi questo articolo contiene istruzioni dettagliate su come scaricare e installare la libreria client Java ("GData") delle API di dati di Google. Analizzerò tutte le dipendenze e imposterò le variabili di ambiente necessarie. Stai per completare l'acquisto di diversi servizi GData in un attimo.

Utilizzi Eclipse?

Consulta l'articolo Coding in the Shade: Utilizzo di Eclipse con le API di dati di Google.

Installazione delle dipendenze

La libreria client Java di GData presenta le seguenti dipendenze esterne. Le sezioni seguenti descrivono come installare queste dipendenze dal tuo sistema operativo preferito (o dal sistema operativo con cui ti blocchi al lavoro).

  • JDK (Java Development Kit) versione 1.5+
  • Apache Ant versione 1.7+
  • mail.jar nell'API JavaMail di Sun 1.4 o versioni successive
  • activate.jar in JavaBeansActivateonFramework di Sun. Questo passaggio è obbligatorio 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 nella versione 2.3 o successiva dell'API Servlet di Sun. È necessaria solo se esegui esempi di codice nei pacchetti "sample.authsub" o "sample.gbase.Recipe".

Alcune delle dipendenze .jar sono obbligatorie solo per esempi specifici, ma per evitare errori nella build è meglio ottenere tutto. Scegli il sistema operativo che preferisci per continuare: Windows, Mac OS X o Linux.

Installare la libreria client di dati di Google

  1. Visita la pagina http://code.google.com/p/gdata-java-client/download/list
  2. Scarica la versione più recente 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 rimandino alle posizioni dei file .jar sulla 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

Campioni in esecuzione

Tutti gli esempi disponibili sono disponibili in gdata/java/sample nell'archivio gdata-samples.java-1.x.x.java.zip. Il file gdata/java/build-samples/build.properties contiene tutti i valori di input per gli esempi contenuti nella libreria. Imposta sample.credentials.username e sample.credentials.password con un nome utente e una password validi. Possiamo usare Ant per creare ed eseguire campioni.

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

Anche se potresti ricevere informazioni o messaggi di avviso, cerca semplicemente il messaggio BUILD SUCCESSFUL alla fine. Se non ricevi un messaggio di operazione riuscita, consulta la sezione relativa alla risoluzione dei problemi.

Prova un'anteprima più interattiva digitando:

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

Per scoprire come eseguire un determinato campione, 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 riesce e restituisce un messaggio di errore, ad esempio

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, è possibile che tu stia eseguendo una versione precedente di Ant. Digita ant -version per assicurarti di eseguire 1.7 o versioni successive. Consulta le istruzioni per la dipendenza riportate sopra per ottenere l'ultima versione di Ant.

Creazione delle proprie applicazioni

La prossima domanda è la creazione della tua applicazione. Vedremo un programma equivalente "Hello World!" utilizzando il servizio Calendar per mostrare le funzionalità di base. Maggiori informazioni sono disponibili nella Guida per gli sviluppatori della Libreria client Java, nonché nelle singole guide per gli sviluppatori del prodotto.

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

Quindi viene impostato l'URL della risorsa. In questo caso, puoi richiedere l'elenco di tutti i calendari all'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 loop for che segue itera ogni voce e stampa il titolo. Tieni presente che il titolo è memorizzato come TextConstruct, pertanto per ricevere il testo normale è necessaria una chiamata a funzione aggiuntiva.

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

La risposta è semplice, vediamo alcune altre cose comuni. Il seguente snippet mostra come creare un oggetto e inserirlo. Per il nostro esempio, si tratta di 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 consiste nell'eseguire il dump del file XML non elaborato. Nella raccolta è disponibile una pratica utilità che puoi usare per farlo. Assicurati che il file samples.util.* sia importato. Quindi, scarica il feed o la voce.

CommonUtils.dump(resultFeed, System.out);

Per strumenti di debug ancora più approfonditi, consulta l'articolo Debugging Google Data API Clients: Exploring Traffic from Within your Program su come attivare il logging dalla libreria client.

Questo dovrebbe darti un'idea dell'aspetto della creazione di app utilizzando la libreria client. Per informazioni più dettagliate, consulta la sezione Conclusione per un elenco di guide per sviluppatori disponibili per ciascuna API di dati di Google.

Conclusione

Spero che tu sia in grado di creare ed eseguire applicazioni utilizzando la libreria client Java di GData. Non ho esaminato nessuno degli IDE più diffusi che potete utilizzare, ma potreste esaminare strumenti popolari come Eclipse o NetBeans. Ecco alcuni link aggiuntivi che potrebbero essere utili:

In caso di domande sull'utilizzo della Libreria client Java con qualsiasi API, puoi contattarci pubblicando un post nei forum specifici dell'API.