Começar a usar a biblioteca de cliente Java dos dados do Google

Stephanie Liu, equipe de APIs de dados do Google
Setembro de 2007
  1. Introdução
  2. Como instalar dependências
    1. No Windows
    2. No Mac OS X
    3. No Linux
  3. Como instalar a biblioteca de cliente de dados do Google
  4. Amostras de execução (link em inglês)
  5. Como criar seus próprios aplicativos
  6. Conclusão
  7. Apêndice: como definir variáveis de ambiente

Introdução

Nunca é fácil começar a desenvolver com uma API desconhecida. Por isso, este artigo contém instruções detalhadas sobre como fazer o download e instalar a biblioteca de cliente Java das APIs de dados do Google (GData). Vou analisar todas as dependências e configurar as variáveis de ambiente necessárias. Você vai fazer o mashup de diferentes serviços do GData rapidamente.

Você usa o Eclipse?

Confira o artigo Códigos na sombra: como usar o Eclipse com as APIs de dados do Google (em inglês).

Como instalar dependências

A biblioteca de cliente Java de dados do Google tem as seguintes dependências externas. As seções a seguir descrevem como instalar essas dependências no seu sistema operacional favorito (ou no sistema operacional que você usa).

  • JDK (Java Development Kit) versão 1.5 ou mais recente
  • Apache Ant versão 1.7+
  • mail.jar na API SunMail 1.4 ou mais recente
  • ativação.jar no JavaBeansActivationFramework da Sun. Isso só é necessário para APIs de mídia específica, incluindo API Data List Data, API Picasa Web Album e API Data do YouTube.
  • servlet.jar na versão 2.3 ou mais recente da API Servlet do Sun. Isso é necessário somente se você estiver executando amostras de código nos pacotes "sample.authsub" ou "sample.gbase.Recipe".

Algumas das dependências de .jar são necessárias apenas para amostras específicas, mas, para evitar erros de compilação, o melhor é conseguir tudo. Escolha o sistema operacional de sua preferência para continuar: Windows, Mac OS X ou Linux.

Como instalar a biblioteca de cliente de dados do Google

  1. Acesse http://code.google.com/p/gdata-java-client/downloads/list
  2. Faça o download da versão mais recente da biblioteca de cliente (gdata-src.java-1.x.x.java.zip) e das amostras (gdata-samples.java-1.x.x.java.zip).
  3. Extraia a origem da biblioteca de cliente no computador.
  4. Acesse gdata/java/build-src/build.properties e abra o arquivo.
  5. Edite as dependências externas para apontar para os locais dos arquivos .jar na máquina local.

    6. Observação: faça o escape das barras invertidas no Windows. Por exemplo:

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

Como executar amostras

Todas as amostras disponíveis estão em gdata/java/sample no arquivo gdata-samples.java-1.x.x.java.zip. O arquivo gdata/java/build-samples/build.properties contém todos os valores de entrada para as amostras da biblioteca. Defina sample.credentials.username e sample.credentials.password como um nome de usuário e uma senha válidos. Podemos usar o Ant para criar e executar as amostras.

Para verificar se você instalou tudo corretamente, abra um prompt de comando, mude para o diretório gdata/java e digite:

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

Talvez você receba algumas informações ou mensagens de aviso, mas procure a mensagem BUILD SUCCESSFUL no final. Consulte a seção de solução de problemas se você não receber uma mensagem de sucesso.

Experimente uma amostra mais interativa digitando:

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

Para descobrir como executar uma amostra específica, acesse gdata/java/build-samples e verifique o arquivo de build desse exemplo. Procure a seção samples run.

Solução de problemas

Se o build falhar com uma mensagem de erro como

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 uma mensagem de erro semelhante sobre um arquivo essencial ausente no projeto, talvez você esteja executando uma versão mais antiga do Ant. Digite ant -version para garantir que a versão seja a 1.7 ou mais recente. Consulte as instruções de dependência acima para acessar a versão mais recente do Ant.

Como criar seus próprios aplicativos

A próxima pergunta é como criar seu próprio aplicativo. Vou passar por um programa equivalente "Hello, World!" usando o serviço Agenda para exibir a funcionalidade básica. Veja informações mais detalhadas no guia do desenvolvedor da biblioteca de cliente Java e nos guias do desenvolvedor de produtos individuais.

Crie um arquivo chamado CalendarTest.java. Comece incluindo as instruções de importação a seguir.

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

Veja o programa inteiro (sem nenhuma exceção de exceção).

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

Em seguida, o URL do recurso é definido. Nesse caso, é possível solicitar a lista de todas as agendas do usuário autenticado.

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

A linha abaixo executará o comando GET real no URL e colocará o feed resultante em um objeto organizado.

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

O loop for abaixo vai iterar em cada entrada e imprimir o título. Como o título é armazenado como uma TextConstruct, uma chamada de função extra é necessária para acessar o texto simples.

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

Isso foi muito básico. Vamos ver outras coisas comuns. O snippet a seguir mostra como criar e inserir um objeto. No nosso exemplo, será uma nova entrada de evento da 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);

Outra operação comum é criar uma consulta.

//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 a depuração, outra operação útil é despejar o XML bruto. Há um utilitário útil que você pode usar para fazer isso na biblioteca. samples.util.* precisa ser importado. Em seguida, despeja o feed ou a entrada.

CommonUtils.dump(resultFeed, System.out);

Para ver ferramentas de depuração ainda mais detalhadas, confira nosso artigo Depuração de clientes da API Google Data: como explorar o tráfego no programa sobre como ativar a geração de registros na biblioteca de cliente.

Isso deve dar uma ideia de como é criar aplicativos usando a biblioteca de cliente. Para informações mais detalhadas, consulte a seção de conclusão para ver uma lista de guias do desenvolvedor disponíveis para cada API de dados do Google.

Conclusão

Esperamos que agora você possa criar e executar aplicativos usando a biblioteca de cliente Java de dados do Google. Não usei um ambiente de desenvolvimento integrado conhecido. No entanto, recomendamos usar ferramentas muito usadas, como o Eclipse ou o NetBeans. Veja outros links que podem ser úteis:

Se você tiver dúvidas sobre como usar a biblioteca de cliente Java com qualquer API, poste nos fóruns específicos da API.