Primeiros passos com a biblioteca de cliente Java de 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 do Google Data
  4. Como executar exemplos
  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 tem instruções detalhadas sobre como baixar e instalar a biblioteca de cliente Java das APIs Google Data ("GData"). Vou mostrar como conseguir todas as dependências e definir as variáveis de ambiente necessárias. Em pouco tempo, você vai estar combinando diferentes serviços do GData!

Você usa o Eclipse?

Confira o artigo Coding in the Shade: Using Eclipse with Google Data APIs (em inglês).

Como instalar dependências

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

  • JDK (Java Development Kit) versão 1.5 ou mais recente
  • Apache Ant versão 1.7 ou mais recente
  • mail.jar na API JavaMail 1.4+ da Sun
  • activation.jar no JavaBeansActivationFramework da Sun. Isso só é necessário para APIs específicas de mídia, incluindo a API Document List Data, a API Picasa Web Album e a API YouTube Data.
  • servlet.jar na API Servlet da Sun versão 2.3 ou mais recente. Isso é necessário apenas se você executar exemplos de código nos pacotes "sample.authsub" ou "sample.gbase.recipe".

Algumas das dependências .jar são necessárias apenas para amostras específicas, mas para evitar erros de build, é melhor pegar tudo. Escolha o sistema operacional 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 dos exemplos (gdata-samples.java-1.x.x.java.zip).
  3. Extraia a fonte da biblioteca de cliente para o computador.
  4. Navegue até 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 sua máquina local.

    6. Observação:no Windows, coloque barras invertidas como escape. Por exemplo,

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

Execução de 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 das amostras na 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 testar 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

Você pode receber algumas informações ou mensagens de aviso, mas basta procurar a mensagem BUILD SUCCESSFUL no final. Consulte a seção de solução de problemas se não receber uma mensagem de sucesso.

Para testar uma amostra mais interativa, digite:

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

Para saber como executar uma amostra específica, acesse gdata/java/build-samples e verifique o arquivo de build dela. 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 do projeto, talvez você esteja executando uma versão mais antiga do Ant. Digite ant -version para verificar se você está usando a versão 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 mostrar um programa equivalente ao "Hello, World!" usando o serviço Calendar para exibir funcionalidades básicas. Para mais informações, consulte o guia para desenvolvedores da biblioteca de cliente Java e os guias para desenvolvedores de cada produto.

Crie um arquivo chamado CalendarTest.java. Comece incluindo as seguintes declaraçõ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.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.*;

Confira o programa completo (sem tratamento de exceções).

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, é aqui que você pode 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 vai executar o comando GET 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. O título é armazenado como um TextConstruct. Portanto, uma chamada de função extra é necessária para receber 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 bem básico. Vamos ver algumas 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 prático que pode ser usado para fazer isso na biblioteca. Verifique se samples.util.* foi importado. Em seguida, despeje o feed ou a entrada.

CommonUtils.dump(resultFeed, System.out);

Para ferramentas de depuração ainda mais detalhadas, confira nosso artigo Depuração de clientes da API Google Data: como analisar o tráfego no seu programa sobre como ativar o registro em log na biblioteca de cliente.

Assim, você vai ter uma ideia de como é criar apps usando a biblioteca de cliente. Para mais detalhes, 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ê consiga criar e executar aplicativos usando a biblioteca de cliente Java do GData. Não entrei em nenhum dos IDEs mais usados, mas você pode pesquisar ferramentas conhecidas como Eclipse ou NetBeans. Confira alguns links adicionais que podem ser úteis:

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