Questo documento descrive come utilizzare la libreria client Java per inviare query Google Data API ("GData") e interpretare le risposte restituite.
Google fornisce un insieme di librerie client, in una serie di linguaggi di programmazione, per interagire con i servizi che dispongono di API di dati. Utilizzando queste librerie, puoi creare richieste GData, inviarle a un servizio e ricevere risposte.
Questo documento fornisce alcune informazioni generali sull'utilizzo della libreria client Java, insieme a una serie di esempi di utilizzi comuni.
Per utilizzare questa libreria client, devi eseguire Java 1.5.
Scarica la libreria client Java.
Gli esempi di questa guida fanno riferimento all'API Google Calendar, ma questa guida non è una guida accurata o aggiornata all'utilizzo dell'API Calendar. Per informazioni sull'utilizzo della libreria client Java con l'API Data di un servizio specifico, consulta la documentazione specifica del servizio. Ad esempio, se utilizzi Calendar, leggi la Guida per gli sviluppatori dell'API Calendar Data.
Sommario
Pubblico
Questo documento è destinato ai programmatori Java che vogliono scrivere applicazioni client in grado di interagire con i servizi GData.
Questo documento presuppone che tu comprenda le idee generali alla base del protocollo Google Data APIs. Si presuppone inoltre che tu sappia programmare in Java.
Per informazioni di riferimento sulle classi e sui metodi forniti dalla libreria client, consulta la documentazione di riferimento dell'API della libreria client Java (in formato Javadoc).
Questo documento è progettato per essere letto in ordine, in quanto ogni esempio si basa su quelli precedenti.
Panoramica del modello di dati
La libreria client Java utilizza un insieme di classi per rappresentare gli elementi utilizzati dalle API Google Data. Ad esempio, esiste una classe Feed, che corrisponde all'elemento <atom:feed>; ha metodi per creare una voce, ottenere e impostare i valori di vari elementi secondari e così via. Esiste anche una classe Entry, che corrisponde all'elemento <atom:entry>. Non tutti gli elementi definiti nelle API Google Data hanno una propria classe. Per maggiori dettagli, consulta la documentazione di riferimento.
La libreria può analizzare automaticamente i contenuti Atom e inserire i valori degli elementi Atom negli oggetti appropriati. Ad esempio, il metodo getFeed recupera un feed, lo analizza e restituisce un oggetto Feed con i valori risultanti.
Per inviare un feed o una voce a un servizio, crea un oggetto Feed o Voce, quindi chiama un metodo della libreria (ad esempio il metodo insert) per tradurre automaticamente l'oggetto in XML e inviarlo.
Se preferisci, puoi analizzare e/o generare autonomamente XML; il modo più semplice per farlo è utilizzare una libreria di terze parti appropriata come Rome.
Proprio come la sintassi XML dell'API Google Data è estensibile, anche il modello a oggetti corrispondente è estensibile. Ad esempio, la libreria client fornisce classi corrispondenti agli elementi definiti nello spazio dei nomi Google Data.
Tutorial ed esempi
Gli esempi riportati di seguito mostrano come inviare varie richieste dell'API Data utilizzando la libreria client Java.
Per renderli più concreti, questi esempi mostrano come interagire con un servizio specifico: Google Calendar. Indicheremo i punti in cui Calendar differisce da altri servizi Google per aiutarti ad adattare questi esempi per l'utilizzo con altri servizi. Per ulteriori informazioni su Calendar, consulta la documentazione dell'API Google Calendar Data.
Creazione ed esecuzione del client
Per compilare gli esempi in questo documento, devi utilizzare 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.extensions.*; import com.google.gdata.util.*; import java.net.URL;
Richiedere un feed
Come descritto nel documento API Google Calendar Data, puoi richiedere un feed di Calendar inviando la seguente richiesta HTTP a Calendar:
GET http://www.google.com/calendar/feeds/userID/private/full
Naturalmente, devi sostituire userID con l'indirizzo email dell'utente. Per maggiori dettagli, consulta il documento di Calendar. Puoi invece utilizzare l'URL predefinito speciale per interagire con Calendar (come descritto nel documento Calendar), ma in questo documento utilizzeremo l'URL del feed completo privato, che contiene l'ID utente.
Devi anche fornire un'autenticazione appropriata. Le principali differenze tra questo esempio e il primo esempio nel documento Calendar sono che (1) questo esempio include l'autenticazione e (2) questo esempio utilizza la classe GoogleService più generale anziché la classe CalendarService specifica per Calendar.
Tieni presente che il sistema di autenticazione che utilizziamo qui (noto come "Autenticazione Google per applicazioni installate") è appropriato solo per l'utilizzo in applicazioni client installate come i client desktop, non per l'utilizzo in applicazioni web. Per saperne di più sull'autenticazione, consulta la documentazione relativa all'autenticazione dell'account Google.
Per richiedere un feed di Calendar utilizzando la libreria client Java per un utente con indirizzo email "liz@gmail.com" e password "mypassword", utilizza il seguente codice:
// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");
// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());
// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);
La classe GoogleService rappresenta una connessione client (con autenticazione) a un servizio GData. La procedura generale per inviare una query a un servizio utilizzando la libreria client prevede i seguenti passaggi:
- Ottieni o crea l'URL appropriato.
- Se invii dati a un servizio (ad esempio, se inserisci una nuova voce), trasforma i dati non elaborati in oggetti utilizzando le classi della libreria client. Questo passaggio non è applicabile se stai solo richiedendo un feed, come in questo esempio.
- Crea una nuova istanza
GoogleService, impostando il nome del servizio (ad esempio"cl"per Calendar) e il nome dell'applicazione (nel formatocompanyName-applicationName-versionID). - Imposta le credenziali appropriate.
- Indica alla libreria client quali estensioni utilizzerà il feed, in modo che la libreria possa analizzare correttamente i feed restituiti.
- Chiama un metodo per inviare la richiesta e ricevere eventuali risultati.
Il metodo setUserCredentials specifica l'ID e la password dell'utente per conto del quale il client invia la query. Gli esempi in questo documento utilizzano il sistema di autenticazione "Autenticazione per applicazioni installate". Per saperne di più sui sistemi di autenticazione, consulta la documentazione relativa all'autenticazione dell'Account Google.
Dopo aver impostato le credenziali, indica quali estensioni utilizzerà il feed chiamando il metodo declareExtensions. In questo caso, stiamo dicendo che il feed è un feed di eventi e quindi utilizzerà le estensioni definite dal tipo di evento.
Per richiedere un intero feed, chiama il metodo getFeed, che accetta un URL e restituisce l'intero feed trovato all'URL. Più avanti in questo documento ti mostreremo come inviare query più specifiche.
Come altri metodi della classe GoogleService, getFeed gestisce l'autenticazione e i reindirizzamenti in base alle necessità.
Inserimento di un nuovo elemento
Per creare un nuovo evento del calendario, puoi utilizzare il seguente codice:
URL postUrl =
new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();
myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));
Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);
DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);
// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);Dopo aver impostato l'URL, creiamo un oggetto EventEntry; EventEntry deriva dalla classe base astratta BaseEntry, che è anche la classe principale per la classe Entry, che rappresenta un elemento <atom:entry>.
La classe EventEntry rappresenta un tipo di evento. Per maggiori informazioni, consulta il documento Tipi. Per i servizi diversi da Calendar, potresti assegnare la voce restituita a un oggetto Entry anziché a un oggetto EventEntry.
Il titolo della voce è un TextConstruct, una classe che contiene testo in varie forme (testo normale, HTML o XHTML). I contenuti della voce sono rappresentati da un oggetto Content, una classe che può contenere testo normale o altre forme di contenuti, inclusi dati XML e binari. (ma il metodo setContent può accettare anche un TextConstruct).
Ogni autore è rappresentato da un nome, un URI e un indirizzo email. In questo esempio, omettiamo l'URI. Per aggiungere un autore a una voce, chiama il metodo getAuthors().add della voce.
Utilizziamo lo stesso oggetto GoogleService che abbiamo creato nell'esempio precedente. In questo caso, il metodo da chiamare è insert, che invia un elemento all'URL di inserimento specificato.
Il servizio restituisce la voce appena creata, che potrebbe contenere elementi aggiuntivi generati dal server, ad esempio un URL di modifica per la voce.
I codici di stato HTTP vengono restituiti come eccezioni.
Il codice precedente equivale a inviare POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (con l'autenticazione corretta) e a fornire una voce sotto forma di tipo Evento.
Richiedere una voce specifica
Il seguente codice ti consente di richiedere la voce specifica che hai inserito nell'esempio precedente.
Nel contesto di questa serie di esempi, il recupero di questa voce non è realmente necessario, perché Calendar ha già restituito la voce inserita. Tuttavia, la stessa tecnica può essere applicata ogni volta che conosci l'URI di una voce.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
La voce inserita ha un metodo, getSelfLink, che restituisce un oggetto Link che include l'URL della voce. La classe Link ha un metodo getHref che restituisce l'URL come String, da cui possiamo creare un oggetto URL.
A questo punto, dobbiamo solo chiamare il metodo getEntry del servizio per ottenere la voce.
Tieni presente che forniamo EventEntry.class come parametro a getEntry, indicando che ci aspettiamo specificamente che il servizio restituisca un evento anziché una semplice voce. Per i servizi diversi da Calendar, puoi passare semplicemente Entry.class.
Il codice precedente equivale all'invio di GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID a Calendar, con l'autenticazione corretta.
Ricerca di voci
Per recuperare la prima corrispondenza da una ricerca a testo intero, utilizza il seguente codice:
Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}Questo esempio inizia creando un oggetto Query, che consiste principalmente in un URL più i parametri di query associati. Ciascuno dei parametri di query GData standard ha un metodo setter. Puoi anche impostare parametri di query personalizzati per un servizio specifico utilizzando il metodo addCustomParameter.
Dopo aver creato Query, lo passiamo al metodo query del servizio, che restituisce un feed contenente i risultati della query. Un approccio alternativo consiste nel creare un URL (aggiungendo parametri di query all'URL del feed) e poi chiamare il metodo getFeed, ma il metodo query fornisce un utile livello di astrazione in modo da non dover creare l'URL.
Il metodo getEntries del feed restituisce un elenco delle voci del feed, mentre getEntries().size restituisce il numero di voci del feed.
In questo caso, se la query ha restituito risultati, assegniamo il primo risultato corrispondente a un oggetto Entry. Poi utilizziamo il metodo getTitle().getPlainText della classe Entry per recuperare il titolo della voce e convertirlo in testo.
Il codice riportato sopra equivale all'invio di GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis a Calendar.
Eseguire query per categoria
Nota: Google Calendar non associa le etichette agli eventi, quindi questo esempio non funziona con Calendar.
Per recuperare un feed composto da tutte le voci che corrispondono alla ricerca full-text precedente e che si trovano in una determinata categoria o hanno una determinata etichetta, utilizza il seguente codice:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);La classe Category, ovviamente, rappresenta una categoria da utilizzare in un filtro per categoria. La classe Query.CategoryFilter può contenere più categorie, ma in questo caso stiamo creando un filtro con una sola categoria.
Aggiungiamo quindi questo filtro alla query esistente, che contiene ancora la stringa di query full-text dell'esempio precedente.
Utilizziamo di nuovo il metodo query per inviare la query al servizio.
Se Calendar consentisse una ricerca per categoria, il codice precedente equivarrebbe all'invio di GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis a Calendar.
Aggiornamento di un elemento
Per aggiornare un elemento esistente, utilizza il seguente codice. In questo esempio, modifichiamo il titolo della voce recuperata in precedenza dal testo precedente ("Tennis con Darcy") in "Riunione importante".
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Innanzitutto, impostiamo un nuovo titolo per la voce recuperata in precedenza. Poi otteniamo l'URL di modifica della voce utilizzando il metodo getEditLink. Poi chiamiamo il metodo update del servizio per inviare la voce aggiornata.
Il servizio restituisce la voce aggiornata, incluso un nuovo URL per la nuova versione della voce. Per ulteriori informazioni sulle versioni delle voci, consulta la sezione Ottimismo concorrente del documento di riferimento del protocollo.
Il codice precedente equivale approssimativamente all'invio di PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID al servizio, insieme alla nuova voce (in formato Atom) per sostituire la voce originale.
Eliminazione di un elemento
Per eliminare la voce aggiornata, utilizza il seguente codice:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
L'URL da utilizzare per l'eliminazione è lo stesso dell'URL di modifica, quindi questo esempio è molto simile al precedente, tranne ovviamente per il fatto che chiamiamo il metodo delete anziché update.
Il codice riportato sopra equivale approssimativamente all'invio di DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID al servizio.
Riferimento
Per informazioni di riferimento sulle classi e sui metodi forniti dalla libreria client, consulta la documentazione di riferimento dell'API della libreria client Java (in formato Javadoc).