Comienza a usar la biblioteca cliente de Google Data para Java

Stephanie Liu, equipo de las APIs de datos de Google
Septiembre de 2007
  1. Introducción
  2. Instalar dependencias
    1. En Windows
    2. En Mac OS X
    3. En Linux
  3. Instala la biblioteca cliente de Google Data
  4. Ejecución de muestras
  5. Cómo crear tus propias aplicaciones
  6. Conclusión
  7. Apéndice: Configuración de variables de entorno

Introducción

Nunca es fácil comenzar a desarrollar con una API desconocida, por lo que este artículo incluye instrucciones paso a paso para descargar e instalar la biblioteca cliente de Java de las APIs de Google Data ("GData"). Te guiaré por el proceso para obtener todas las dependencias y establecer las variables de entorno que necesitarás. Combinarás diferentes servicios de GData en muy poco tiempo.

¿Usas Eclipse?

Consulta el artículo Coding in the Shade: Using Eclipse with Google Data APIs.

Instala dependencias

La biblioteca cliente de GData para Java tiene las siguientes dependencias externas. En las siguientes secciones, se describirá cómo instalar estas dependencias en tu sistema operativo favorito (o en el SO que te tocó usar en el trabajo).

  • JDK (Java Development Kit) versión 1.5 o posterior
  • Apache Ant, versión 1.7 o posterior
  • mail.jar en la API de JavaMail 1.4 y versiones posteriores de Sun
  • activation.jar en JavaBeansActivationFramework de Sun. Esto solo es necesario para las APIs específicas de medios, como la API de Document List Data, la API de Picasa Web Album y la API de YouTube Data.
  • servlet.jar en la versión 2.3 o posterior de la API de Servlet de Sun. Esto solo es necesario si se ejecutan muestras de código en los paquetes "sample.authsub" o "sample.gbase.recipe".

Algunas de las dependencias de .jar solo se requieren para muestras específicas, pero, para evitar errores de compilación, lo mejor es obtener todo. Elige el sistema operativo que prefieras para continuar: Windows, Mac OS X o Linux.

Instala la biblioteca cliente de Google Data

  1. Visita http://code.google.com/p/gdata-java-client/downloads/list.
  2. Descarga la versión más reciente de la biblioteca cliente (gdata-src.java-1.x.x.java.zip) y los ejemplos (gdata-samples.java-1.x.x.java.zip).
  3. Extrae la fuente de la biblioteca cliente en tu computadora.
  4. Navega a gdata/java/build-src/build.properties y abre el archivo.
  5. Edita las dependencias externas para que apunten a las ubicaciones de los archivos .jar en tu máquina local.

    6. Nota: En Windows, asegúrate de aplicar formato de escape a las barras inversas. Por ejemplo:

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

Ejecuta muestras

Todas las muestras disponibles se encuentran en gdata/java/sample del archivo gdata-samples.java-1.x.x.java.zip. El archivo gdata/java/build-samples/build.properties contiene todos los valores de entrada para las muestras incluidas en la biblioteca. Establece sample.credentials.username y sample.credentials.password en un nombre de usuario y una contraseña válidos. Podemos usar Ant para compilar y ejecutar las muestras.

Para probar si instalaste todo correctamente, abre un símbolo del sistema, cambia al directorio gdata/java y escribe lo siguiente:

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

Es posible que recibas algunos mensajes de información o advertencia, pero solo busca el mensaje BUILD SUCCESSFUL al final. Si no recibes un mensaje de confirmación, consulta la sección de solución de problemas.

Para probar un ejemplo más interactivo, escribe lo siguiente:

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

Para saber cómo ejecutar una muestra en particular, ve a gdata/java/build-samples y consulta el archivo de compilación de esa muestra. Busca la sección samples run.

Solución de problemas

Si la compilación falla con un mensaje de error como el siguiente:

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

o un mensaje de error similar sobre un archivo esencial que falta en el proyecto, es posible que estés ejecutando una versión anterior de Ant. Escribe ant -version para asegurarte de que ejecutas la versión 1.7 o una posterior. Consulta las instrucciones de dependencia anteriores para obtener la versión más reciente de Ant.

Cómo crear tus propias aplicaciones

La siguiente pregunta es cómo compilar tu propia aplicación. Repasaremos un programa equivalente a "Hello, World!" con el servicio de Calendar para mostrar la funcionalidad básica. En la guía para desarrolladores de la biblioteca cliente de Java, así como en las guías para desarrolladores de los productos individuales, encontrarás información más detallada.

Crea un archivo llamado CalendarTest.java. Comienza por incluir las siguientes instrucciones de importación.

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

Este es el programa completo (sin ningún control de excepciones).

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

Luego, se establece la URL del recurso. En este caso, aquí es donde puedes solicitar la lista de todos los calendarios del usuario autenticado.

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

La siguiente línea ejecutará el comando GET real en la URL y colocará el feed resultante en un objeto ordenado.

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

El bucle for que se muestra a continuación iterará en cada entrada y mostrará el título. Ten en cuenta que el título se almacena como un TextConstruct, por lo que se requiere una llamada de función adicional para obtener el texto sin formato.

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

Eso fue bastante básico. Veamos algunas otras cosas comunes. En el siguiente fragmento, se muestra cómo crear un objeto y cómo insertarlo. En nuestro ejemplo, será una nueva entrada de evento de calendario.

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

Otra operación común es la creación de una 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 la depuración, otra operación útil es volcar el XML sin procesar. Hay una práctica utilidad que puedes usar para hacerlo en la biblioteca. Asegúrate de que se haya importado samples.util.*. Luego, descarta el feed o la entrada.

CommonUtils.dump(resultFeed, System.out);

Para obtener herramientas de depuración aún más detalladas, consulta nuestro artículo Debugging Google Data API Clients: Exploring Traffic from Within your Program sobre cómo activar el registro desde la biblioteca cliente.

Esto te dará una idea de cómo es compilar apps con la biblioteca cliente. Para obtener información más detallada, consulta la sección de conclusiones, en la que se incluye una lista de las guías para desarrolladores disponibles para cada API de datos de Google.

Conclusión

Esperamos que ahora puedas compilar y ejecutar aplicaciones con la biblioteca cliente de GData para Java. No mencioné ninguno de los IDE populares que puedes usar, pero te recomiendo que investigues herramientas populares como Eclipse o NetBeans. Estos son algunos vínculos adicionales que pueden resultarte útiles:

Si tienes alguna pregunta sobre el uso de la biblioteca cliente de Java con alguna API, puedes publicarla en los foros específicos de la API.