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.

Instruções para o sistema operacional Windows.

Instalação do Java

O pacote de desenvolvimento Java está disponível na Sun na forma de JDK (Java Development Kit). O JRE (Java Runtime Environment) e todos os outros recursos necessários para programar, compilar, testar e depurar aplicativos Java estão contidos nele. Se o Java já estiver instalado, avance para a instalação do Ant.

Observação:é preciso ter permissões administrativas para instalar o JDK.

  1. Acesse http://java.sun.com/javase/downloads/index.jsp
  2. Clique em "Download" ao lado da atualização mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Faça o download de um dos arquivos de instalação do Windows.
  5. Execute o instalador.
  6. Edite a variável de ambiente Path para executar facilmente os executáveis do JDK, como javac. O caminho que você quer adicionar é semelhante a C:\jdk\bin\. Consulte o Apêndice para ver instruções sobre como editar a variável Path no Windows.

Se você tiver problemas para instalar o JDK, confira as instruções detalhadas de instalação no site do Sun.

Como instalar o Ant

O Apache Ant é uma ferramenta de build para Java semelhante a make (mas melhor). Você vai usá-lo para criar a biblioteca e executar amostras. Se você já tem o Ant instalado, verifique se é a versão 1.7 ou mais recente.

  1. Clique no menu "Iniciar" e em "Executar".
  2. Digite cmd no campo de texto.
  3. Digite ant -version na solicitação para ver qual é sua versão.

Se você tiver a versão 1.7 ou versões mais recentes, acesse o mail.jar. Caso sua versão do Ant seja anterior à 1.7 ou não esteja instalada, siga as etapas abaixo.

  1. Acesse http://ant.apache.org/bindownload.cgi.
  2. Clique no link de download do arquivo .zip.
  3. Extraia todos os arquivos no local que você preferir, como C:\ant
  4. Adicione o diretório ant bin, como C:\ant\bin, à variável de ambiente Path.
  5. Adicione ou edite a variável de ambiente ANT_HOME para defini-la como o novo local. Por exemplo: C:\ant
  6. Adicione ou edite a variável de ambiente JAVA_HOME em que o Java está instalado (por exemplo, C:\jdk).

Veja instruções detalhadas de instalação no site do Ant se tiver algum problema.

Receber mail.jar

A API JavaMail está disponível para suporte de mídia.

  1. Acesse http://java.sun.com/products/javamail/downloads/index.html
  2. Clique no botão "Download". Faça o download da versão 1.4 ou mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link para o arquivo .zip que contém JavaMail.
  5. Extraia os arquivos no seu computador e anote o local. mail.jar estará no diretório raiz, javamail-(version)

Como receber o active.jar

O JavaBeans Activation Framework inclui suporte de mídia.

  1. Acesse a página de download do JAF.
  2. Clique no botão "Download".
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link do arquivo .zip que contém o framework de ativação.
  5. Extraia os arquivos no seu computador e anote o local. activation.jar estará no diretório raiz, jaf-(version)

Como receber o servlet.jar

servlet.jar (pode ser chamado de servlet-api.jar) pode ser encontrado no contêiner do seu servlet (J2EE, Tomcat, WebLogic etc.). Ele é usado para as amostras XPN e Google Base. As instruções a seguir mostram como usar o Tomcat 6.x.

  1. Acesse http://tomcat.apache.org/download-60.cgi
  2. Clique no download do Instalador de Serviço do Windows em "Principais distribuições binárias".
  3. Execute o instalador.
  4. Se você manteve a configuração padrão, o servlet-api.jar precisa estar localizado em C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib.

Veja mais documentação de configuração e instalação do Tomcat aqui.

Parabéns, agora está tudo pronto para instalar a biblioteca de cliente Java dos dados do Google.

Instruções para o sistema operacional Mac OS X.

Instalação do Java

Se estiver executando o Mac OS X, você terá menos trabalho para fazer. A Apple incluiu um JDK (Java Development Kit) totalmente configurado e pronto para uso em cada instância. Acesse o site Java da Apple para mais informações.

Como instalar o Ant

O Apache Ant é uma ferramenta de build para Java semelhante a make (mas melhor). Você vai usá-lo para criar a biblioteca e executar amostras. É provável que você já tenha o Ant instalado, mas verifique se tem a versão 1.7 ou mais recente.

  1. Abra uma janela de terminal. Pressione Command + barra de espaço e digite "Terminal" para encontrar o app.
  2. No prompt de comando, digite:
    3. ant -version

Se a versão do Ant que você está executando for anterior à versão 1.7, siga as etapas abaixo para instalar a versão mais recente.

  1. Acesse http://ant.apache.org/bindownload.cgi.
  2. Clique no link de download do arquivo .zip.
  3. Abra uma janela de terminal. Pressione Command + barra de espaço e digite "Terminal" para encontrar o app.
  4. No prompt de comando, digite o seguinte:
    • cd ~/Desktop
    • sudo sh
    • mv apache-ant-(version)-bin.zip /usr/local/
    • cd /usr/local/
    • unzip apache-ant-(version)-bin.zip
    • chown (your account name):(your account name) apache-ant-(version)
    • ln -s apache-ant-(version) ant

Veja instruções detalhadas de instalação no site do Ant se tiver algum problema. Esta postagem do blog também tem uma explicação detalhada do significado dos comandos do shell acima.

Receber mail.jar

A API JavaMail está disponível para suporte de mídia.

  1. Acesse http://java.sun.com/products/javamail/downloads/index.html
  2. Clique no botão "Download". Faça o download da versão 1.4 ou mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link para o arquivo .zip que contém JavaMail.
  5. Extraia os arquivos no seu computador e anote o local. mail.jar estará no diretório raiz, javamail-(version)

Como receber o active.jar

O JavaBeans Activation Framework inclui suporte de mídia.

  1. Acesse a página de download do JAF.
  2. Clique no botão "Download".
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link do arquivo .zip que contém o framework de ativação.
  5. Extraia os arquivos no seu computador e anote o local. activation.jar estará no diretório raiz, jaf-(version)

Como receber o servlet.jar

servlet.jar (pode ser chamado de servlet-api.jar) pode ser encontrado no contêiner do seu servlet (J2EE, Tomcat, WebLogic etc.). Ele é usado para as amostras XPN e Google Base. As instruções a seguir mostram como usar o Tomcat 6.x.

  1. Acesse http://tomcat.apache.org/download-60.cgi
  2. Clique no download de .zip em "Principais distribuições binárias".
  3. Extraia os arquivos no seu computador e anote o local. O servlet.jar será encontrado em apache-tomcat-(version)/lib

Veja mais documentação de configuração e instalação do Tomcat aqui.

Parabéns, agora está tudo pronto para instalar a biblioteca de cliente Java dos dados do Google.

Instruções para o sistema operacional Linux.

Instalação do Java

Neste tutorial, usaremos o JDK (Java Development Kit) do Sun. Se você tiver acesso à raiz, siga as instruções abaixo. Caso contrário, basta instalar o JDK no seu diretório inicial seguindo estas instruções. Se o JDK 1.5+ já estiver instalado, avance para Como instalar o Ant.

Se você tiver privilégios raiz:

  1. Acesse http://java.sun.com/javase/downloads/index.jsp
  2. Clique em "Download" ao lado da versão mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Clique e faça o download do arquivo RPM com extração automática em "Plataforma Linux".
  5. Abra uma janela do terminal, mude para o diretório em que você fez o download do arquivo e faça o seguinte:
    • su
    • chmod a+x jdk-6(version)-linux-i586-rpm.bin
    • ./jdk-6(version)-linux-i586-rpm.bin
    • Concorde com o contrato de licença.

Se você não tiver privilégios raiz:

  1. Acesse http://java.sun.com/javase/downloads/index.jsp
  2. Clique em "Download" ao lado da versão mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Clique e faça o download do build de extração automática em vez de RPM em "Plataforma Linux".
  5. Abra uma janela do terminal, acesse o diretório onde você fez o download do arquivo e digite os seguintes comandos:
    • chmod +x jdk-6(version)-linux-i586-rpm.bin
    • Acesse o diretório em que você quer que o arquivo seja instalado.
    • Execute o binário de extração automática. Se ele estiver sendo instalado no diretório atual, basta digitar ./jdk-6(version)-linux-i586-rpm.bin
    • Concorde com o contrato de licença.

Se você tiver problemas, consulte instruções detalhadas de instalação aqui.

Como instalar o Ant

A biblioteca de cliente Java de dados do Google exige Ant 1.7 ou versões mais recentes. Se o Ant já estiver instalado, verifique a versão digitando ant -version em um prompt de comando. Se você precisar da versão mais recente ou não tiver a versão instalada, siga as instruções abaixo. Pule para como conseguir o mail.jar se as instalações Java e Ant já estiverem configuradas.

  1. Acesse http://ant.apache.org/bindownload.cgi.
  2. Clique no link de download do arquivo .tar.gz.
  3. Extraia os arquivos exibindo uma janela de terminal, mudando para o diretório com o arquivo transferido por download e digitando os seguintes comandos:
    • gunzip apache-ant-(version)-bin.tar.gz
    • tar xvf apache-ant-(version)-bin.tar
  4. Adicione o diretório bin da form à variável de ambiente do PATH.
  5. Adicione ou edite a variável de ambiente ANT_HOME para defini-la como o novo local.
  6. Adicione ou edite a variável de ambiente JAVA_HOME para configurá-la como o local em que o JDK está instalado.

A documentação de instalação do Ant pode ser encontrada aqui em caso de problemas.

Receber mail.jar

A API JavaMail está disponível para suporte de mídia.

  1. Acesse http://java.sun.com/products/javamail/downloads/index.html
  2. Clique no botão "Download". Faça o download da versão 1.4 ou mais recente.
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link para o arquivo .zip que contém JavaMail.
  5. Use unzip para salvar os arquivos no seu computador e anote o local. mail.jar estará no diretório raiz, javamail-(version)

Como receber o active.jar

O JavaBeans Activation Framework inclui suporte de mídia.

  1. Acesse a página de download do JAF.
  2. Clique no botão "Download".
  3. Leia e aceite o Contrato de Licença.
  4. Clique no link do arquivo .zip que contém o framework de ativação.
  5. Use unzip para salvar os arquivos no seu computador e anote o local. activation.jar estará no diretório raiz, jaf-(version)

Como receber o servlet.jar

servlet.jar (pode ser chamado de servlet-api.jar) pode ser encontrado no contêiner do seu servlet (J2EE, Tomcat, WebLogic etc.). Ele é usado para as amostras XPN e Google Base. As instruções a seguir mostram como usar o Tomcat 6.x.

  1. Acesse http://tomcat.apache.org/download-60.cgi
  2. Faça o download do arquivo .tar.gz em "Principais distribuições binárias".
  3. Descompacte o download com gunzip e tar, conforme mostrado na seção Como instalar o Ant acima.
  4. O servlet.jar será encontrado em apache-tomcat-(version)/lib

Agora você tem tudo o que precisa para acessar a biblioteca de cliente Java de dados do Google.

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.

Instruções para configurar suas variáveis de ambiente no Windows ou no Linux. Não será necessário definir nada para o Mac OS X.

Windows

As variáveis do sistema são aplicadas a todos os usuários do computador. Se não for possível editar as variáveis do sistema porque você não tem privilégios de administrador, siga estas instruções.

Se você tiver privilégios administrativos:

  1. Clique com o botão direito do mouse em "Meu computador" e selecione "Propriedades".
  2. Clique na guia "Avançado".
  3. Clique em "Variáveis de ambiente".
  4. "Adicionar" ou "Editar" variáveis do sistema: (substitua o local na sua máquina local)
    • Adicione ou edite ANT_HOME e defina o valor como C:\ant.
    • Adicione ou edite JAVA_HOME e defina o valor como C:\jdk.
    • Adicione ou edite Path e anexe ;C:\ant\bin;C:\jdk\bin ao final (o ponto e vírgula separa os caminhos de diretório)
    • Adicione ou edite o CLASSPATH e anexe os arquivos .jar necessários, dependendo dos serviços que você quer usar. Verifique se "." está incluído &mhash. Isso indica o diretório atual. .;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar etc.
  5. Reinicie para garantir que elas entrem em vigor.

Observação: verifique se as variáveis não estão entre aspas ("ou") e não terminam com "\" ou "/".

Se você não tiver privilégios de administrador:

  1. Clique com o botão direito do mouse em "Meu computador" e selecione "Propriedades".
  2. Clique na guia "Avançado".
  3. Clique em "Variáveis de ambiente".
  4. "Adicionar" ou "Editar" variáveis de usuário: (substitua o local na sua máquina local)
    • Adicione ou edite ANT_HOME e defina o valor como C:\ant.
    • Adicione ou edite JAVA_HOME e defina o valor como C:\jdk.
    • Adicione ou edite Path e anexe ;C:\ant\bin;C:\jdk\bin ao final (o ponto e vírgula separa os caminhos de diretório)
    • Adicione ou edite o CLASSPATH e anexe os arquivos .jar necessários, dependendo dos serviços que você quer usar. Verifique se "." está incluído &mhash. Isso indica o diretório atual. .;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar etc.
  5. Reinicie para garantir que elas entrem em vigor.

Observação:verifique se as variáveis não estão entre aspas ("ou") e não terminam com "\" ou "/".

As variáveis de usuário que você acabou de editar serão aplicadas somente ao seu perfil de usuário.

Linux

  1. Abra o arquivo .bash_profile no editor de sua preferência, localizado no diretório principal.
  2. Adicione o seguinte ao seu .bash_profile, substituindo os locais reais dos arquivos na sua máquina:
    • export ANT_HOME=/usr/local/ant
    • export JAVA_HOME=/usr/local/jdk
    • export PATH=${PATH}:${ANT_HOME}/bin
    • Será necessário adicionar os arquivos .jar para os serviços que você usará. Por exemplo, export CLASSPATH=${CLASSPATH}:/home/username/gdata/java/lib/gdata-core-1.0.jar:/home/username/gdata/java/lib/gdata-calendar-1.0.jar:/home/username/gdata/java/sample/util/lib/sample-util.jar
  3. source .bash_profile para estabelecer as variáveis.

Observação:verifique se as variáveis não estão entre aspas ("ou") e não terminam com "\" ou "/".