Este documento descreve como usar a biblioteca de cliente Java para enviar consultas da API Google Data ("GData") e interpretar as respostas retornadas.
O Google oferece um conjunto de bibliotecas de cliente em várias linguagens de programação para interagir com serviços que têm APIs de dados. Com essas bibliotecas, é possível criar solicitações do GData, enviá-las a um serviço e receber respostas.
Este documento fornece algumas informações gerais sobre o uso da biblioteca de cliente Java, além de um conjunto de exemplos de usos comuns.
Para usar essa biblioteca de cliente, você precisa executar o Java 1.5.
Faça o download da biblioteca de cliente Java.
Os exemplos deste guia se referem à API Google Agenda, mas ele não é um guia preciso ou atualizado para usar essa API. Para informações sobre como usar a biblioteca de cliente Java com a API Data de um serviço específico, consulte a documentação específica do serviço. Por exemplo, se você estiver trabalhando com o Google Agenda, leia o guia do desenvolvedor da API de dados do Google Agenda.
Índice
Público-alvo
Este documento é destinado a programadores Java que querem criar aplicativos cliente que possam interagir com os serviços do GData.
Este documento pressupõe que você entenda as ideias gerais por trás do protocolo das APIs Google Data. Também é necessário que você saiba programar em Java.
Para informações de referência sobre as classes e os métodos fornecidos pela biblioteca de cliente, consulte a referência da API da biblioteca de cliente Java (em formato Javadoc).
Este documento foi criado para ser lido em ordem. Cada exemplo se baseia nos anteriores.
Visão geral do modelo de dados
A biblioteca de cliente Java usa um conjunto de classes para representar os elementos usados pelas APIs Google Data. Por exemplo, há uma classe Feed, que corresponde ao elemento <atom:feed>. Ela tem métodos para criar uma entrada, receber e definir os valores de vários subelementos e assim por diante. Há também uma classe "Entry", que corresponde ao elemento <atom:entry>. Nem todos os elementos definidos nas APIs Google Data têm uma classe própria. Para mais detalhes, consulte a documentação de referência.
A biblioteca pode analisar automaticamente o conteúdo do Atom e colocar os valores dos elementos do Atom em objetos apropriados. Por exemplo, o método getFeed recebe um feed, o analisa e retorna um objeto Feed com os valores resultantes.
Para enviar um feed ou uma entrada a um serviço, crie um objeto Feed ou Entry e chame um método de biblioteca (como o método insert) para traduzir automaticamente o objeto em XML e enviá-lo.
Você pode analisar e/ou gerar XML por conta própria, se preferir. A maneira mais fácil de fazer isso é com uma biblioteca de terceiros adequada, como Rome.
Assim como a sintaxe XML da API Google Data é extensível, o modelo de objeto correspondente também é. Por exemplo, a biblioteca de cliente fornece classes correspondentes aos elementos definidos no namespace Google Data.
Tutorial e exemplos
Os exemplos a seguir mostram como enviar várias solicitações da API Data usando a biblioteca de cliente Java.
Para torná-los mais concretos, esses exemplos mostram como interagir com um serviço específico: o Google Agenda. Vamos destacar os pontos em que a Agenda difere de outros Serviços do Google para ajudar você a adaptar esses exemplos para uso com outros serviços. Para mais informações sobre o Google Agenda, consulte a documentação da API de dados do Google Agenda.
Criar e executar o cliente
Para compilar os exemplos neste documento, use as seguintes instruções de importação:
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;
Como pedir um feed
Conforme descrito no documento API Google Calendar Data, é possível solicitar um feed do Google Agenda enviando a seguinte solicitação HTTP para o Google Agenda:
GET http://www.google.com/calendar/feeds/userID/private/full
Substitua userID pelo endereço de e-mail do usuário. Consulte o documento do Google Agenda para mais detalhes. Em vez disso, você pode usar o URL padrão especial para interagir com o Google Agenda (conforme descrito no documento do Google Agenda), mas, neste documento, vamos usar o URL do feed completo particular, que contém o ID do usuário.
Você também precisa fornecer a autenticação adequada. As principais diferenças entre este exemplo e o primeiro no documento do Google Agenda são que (1) este exemplo inclui autenticação e (2) usa a classe GoogleService mais geral em vez da classe CalendarService específica do Google Agenda.
O sistema de autenticação que estamos usando aqui (conhecido como "Autenticação do Google para aplicativos instalados") é adequado apenas para uso em aplicativos cliente instalados, como clientes de computador, e não para uso em aplicativos da Web. Para mais informações sobre autenticação, consulte a documentação Autenticação da Conta do Google.
Para solicitar um feed da Agenda usando a biblioteca de cliente Java de um usuário com o endereço de e-mail "liz@gmail.com" e a senha "mypassword", use o seguinte código:
// 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);
A classe GoogleService representa uma conexão de cliente (com autenticação) a um serviço do GData. O procedimento geral para enviar uma consulta a um serviço usando a biblioteca de cliente consiste nas seguintes etapas:
- Obtenha ou crie o URL adequado.
- Se você estiver enviando dados para um serviço (por exemplo, inserindo uma nova entrada), transforme os dados brutos em objetos usando as classes da biblioteca de cliente. Essa etapa não se aplica se você estiver apenas solicitando um feed, como fazemos neste exemplo.
- Crie uma instância
GoogleService, definindo o nome do serviço (como"cl"para o Google Agenda) e o nome do aplicativo (no formatocompanyName-applicationName-versionID). - Defina as credenciais apropriadas.
- Indique à biblioteca de cliente quais extensões o feed vai usar para que ela possa analisar os feeds retornados corretamente.
- Chame um método para enviar a solicitação e receber os resultados.
O método setUserCredentials especifica o ID e a senha do usuário em nome de quem o cliente está enviando a consulta. Os exemplos neste documento usam o sistema de autenticação "Autenticação para aplicativos instalados". Para mais informações sobre sistemas de autenticação, consulte a documentação Autenticação da Conta do Google.
Depois de definir as credenciais, indique quais extensões o feed vai usar chamando o método declareExtensions. Neste caso, estamos dizendo que o feed é um feed de eventos e, portanto, usará as extensões definidas pelo tipo de evento.
Para solicitar um feed inteiro, chame o método getFeed, que recebe um URL e retorna o feed completo encontrado nele. Vamos mostrar como enviar consultas mais específicas mais adiante neste documento.
Assim como outros métodos da classe GoogleService, getFeed processa a autenticação e os redirecionamentos conforme necessário.
Inserir um novo item
Para criar um evento do Google Agenda, use o seguinte código:
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);Depois de definir o URL, construímos um objeto EventEntry. EventEntry é derivado da classe base abstrata BaseEntry, que também é a classe mãe da classe Entry, que representa um elemento <atom:entry>.
A classe EventEntry representa um tipo de evento. Para mais informações, consulte o documento "Tipos". Para serviços diferentes do Agenda, você pode atribuir a entrada retornada a um objeto Entry em vez de um objeto EventEntry.
O título da entrada é um TextConstruct, uma classe que contém texto de várias formas (texto simples, HTML ou XHTML). O conteúdo da entrada é representado por um objeto Content, uma classe que pode conter texto simples ou outras formas de conteúdo, incluindo XML e dados binários. No entanto, o método setContent também pode aceitar um TextConstruct.
Cada autor é representado como um nome, um URI e um endereço de e-mail. Neste exemplo, vamos omitir o URI. Para adicionar um autor a uma entrada, chame o método getAuthors().add dela.
Estamos usando o mesmo objeto GoogleService que criamos no exemplo anterior. Nesse caso, o método a ser chamado é insert, que envia um item para o URL de inserção especificado.
O serviço retorna a entrada recém-criada, que pode conter outros elementos gerados pelo servidor, como um URL de edição para a entrada.
Os códigos de status HTTP são retornados como exceções.
O código acima é equivalente a enviar POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (com autenticação adequada) e fornecer uma entrada na forma de um tipo de evento.
Solicitar uma entrada específica
O código a seguir permite solicitar a entrada específica que você inseriu no exemplo anterior.
No contexto desta série de exemplos, não é necessário recuperar essa entrada porque o Google Agenda já retornou a entrada inserida. No entanto, a mesma técnica pode ser aplicada sempre que você souber o URI de uma entrada.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
A entrada inserida tem um método, getSelfLink, que retorna um objeto Link que inclui o URL da entrada. A classe Link tem um método getHref que retorna o URL como um String, com o qual podemos criar um objeto de URL.
Em seguida, basta chamar o método getEntry do serviço para receber a entrada.
Observe que fornecemos EventEntry.class como um parâmetro para getEntry, indicando que esperamos especificamente que o serviço retorne um evento, e não apenas uma entrada simples. Para serviços diferentes do Agenda, basta transmitir Entry.class.
O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID para o Google Agenda com a autenticação adequada.
Pesquisar entradas
Para recuperar a primeira correspondência de uma pesquisa de texto completo, use o seguinte código:
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();
}Este exemplo começa construindo um objeto Query, que consiste principalmente em um URL mais parâmetros de consulta associados. Cada um dos parâmetros de consulta padrão do GData tem um método setter. Também é possível definir parâmetros de consulta personalizados para um serviço específico usando o método addCustomParameter.
Depois de construir o Query, transmitimos ele ao método query do serviço, que retorna um feed com os resultados da consulta. Uma abordagem alternativa seria construir um URL por conta própria (anexando parâmetros de consulta ao URL do feed) e chamar o método getFeed. No entanto, o método query oferece uma camada útil de abstração para que você não precise construir o URL por conta própria.
O método getEntries do feed retorna uma lista das entradas no feed. Já getEntries().size retorna o número de entradas no feed.
Nesse caso, se a consulta retornar algum resultado, vamos atribuir o primeiro resultado correspondente a um objeto Entry. Em seguida, usamos o método getTitle().getPlainText da classe Entry para recuperar o título da entrada e convertê-lo em texto.
O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis para a Agenda.
Consultar por categoria
Observação: o Google Agenda não associa rótulos a eventos. Portanto, este exemplo não funciona com o Agenda.
Para recuperar um feed com todas as entradas que correspondem à pesquisa de texto completo anterior e que estão em uma categoria específica ou têm um marcador específico, use o seguinte código:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);A classe Category, é claro, representa uma categoria a ser usada em um filtro de categoria. A classe Query.CategoryFilter pode conter várias categorias, mas, neste caso, estamos criando um filtro com apenas uma categoria.
Em seguida, adicionamos esse filtro à consulta atual, que ainda contém a string de consulta de texto completo do exemplo anterior.
Usamos novamente o método query para enviar a consulta ao serviço.
Se o Google Agenda permitisse uma pesquisa por categoria, o código acima seria equivalente ao envio de GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis para o Google Agenda.
Atualizar um item
Para atualizar um item, use o seguinte código. Neste exemplo, vamos mudar o título da entrada recuperada anteriormente do texto antigo ("Tênis com Darcy") para "Reunião importante".
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Primeiro, definimos um novo título para a entrada que buscamos anteriormente. Em seguida, recebemos o URL de edição da entrada usando o método getEditLink. Em seguida, chamamos o método update do serviço para enviar a entrada atualizada.
O serviço retorna a entrada atualizada, incluindo um novo URL para a nova versão dela. Para mais informações sobre versões de entrada, consulte a seção Simultaneidade otimista do documento de referência do protocolo.
O código acima é aproximadamente equivalente ao envio de PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ao serviço, junto com a nova entrada (no formato Atom) para substituir a entrada original.
Excluir um item
Para excluir a entrada atualizada, use o seguinte código:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
O URL usado para exclusão é o mesmo do URL de edição. Portanto, este exemplo é muito semelhante ao anterior, exceto que estamos chamando o método delete em vez de update.
O código acima é aproximadamente equivalente ao envio de DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ao serviço.
Referência
Para informações de referência sobre as classes e os métodos fornecidos pela biblioteca de cliente, consulte a referência da API da biblioteca de cliente Java (em formato Javadoc).