API Google Wave (Лаборатория Google)

Обзор расширений
- API роботов
  - Обзор
  - Клиентская библиотека Java
  - Клиентская библиотека Python
- API гаджетов
  - Руководство
  - Справочное руководство

API встраивания волн
- Руководство
- Справочное руководство

Ресурсы Google Wave

Роботы Google Wave: руководство по Java

Проще всего понять работу расширений Google Wave, создав Wave-робота. Роботы представляют собой приложения, которые взаимодействуют с Google Wave посредством Wave-протокола (HTTP-интерфейса). На данный момент поддерживаются только роботы, размещенные на Google App Engine. В будущем будет обеспечена поддержка клиентской архитектуры, реализующей Wave-протокол.

В этом руководстве для разработки робота используется клиентская библиотека Java. (Описанные здесь концепции применимы и для пользователей клиентской библиотеки Python. Отличие заключается в технической реализации.) В этом кратком руководстве описано создание простого робота, его добавление в App Engine и работа с Google Wave.

Прежде чем начать, убедитесь, что у вас установлен инструментарий разработки Java 6. В будущем выпуске будет предусмотрена поддержка разработки приложений с помощью Java 5. Чтобы определить наличие установки Java и номер установленной версии, нужно выполнить следующую команду в командной строке:

hostname$ java -version
java version "1.6.0_07"
Java(TM) SE Runtime Environment (build 1.6.0_07-b06-153)
Java HotSpot(TM) 64-Bit Server VM (build 1.6.0_07-b06-57, mixed mode)

Примечание. Чтобы включить Java 6 на Mac OS X, может потребоваться сделать Java 6 инструментом по умолчанию с помощью приложения /Applications/Utilties/Java/JavaPreferences.

Клиентская библиотека Java

Для разработки роботов Google Wave нужно скомпилировать клиентскую библиотеку. В этом руководстве используются клиентская библиотека Java, библиотеки JSON и JSON RPC. Эти библиотеки можно загрузить с главной страницы клиентской библиотеки Java для роботов Google Wave на Хостинге проектов Google:

http://code.google.com/p/wave-robot-java-client/

Кроме того, доступна клиентская библиотека Python.

Настройка App Engine

Разрабатывать роботов Google Wave и другие веб-приложения Java для App Engine можно с помощью любых инструментов для разработки на Java. Плагин Google для Eclipse существенно упрощает разработку приложений App Engine с помощью IDE Eclipse. Этот плагин включает SDK Java App Engine и добавляет ряд функций к Eclipse, которые позволяют создавать, тестировать и добавлять проекты.

Регистрация приложения в App Engine

Зарегистрировать робота по идентификатору приложения можно на сайте https://appengine.google.com. Можно зарегистрировать до десяти идентификаторов приложений. Регистрацию приложений нельзя отменить или удалить. Кроме того, нельзя изменить идентификатор приложения после его регистрации. Чтобы зарезервировать выделенные вам регистрации, выберите идентификатор приложения, который впоследствии используете для будущего проекта. Кроме того, можно зарезервировать идентификатор для тестирования роботов.

Перейдите в консоль администрирования App Engine в веб-браузере. Выполните вход, используя аккаунт Google. При необходимости создайте аккаунт. Если этот аккаунт не использовался для App Engine, может потребоваться подтвердить его посредством SMS и мобильного телефона.

В области Мои приложения нажмите кнопку Создать приложение. Выберите идентификатор приложения и следуйте инструкциям по завершению регистрации. Новое приложение появится в списке. Чтобы перейти в консоль администрирования для этого приложения, нажмите на его название.

Настройка Eclipse

Для краткости в этом руководстве предполагается, что вы используете Eclipse и плагин Google. Все функции плагина также предоставлены в SDK App Engine в виде задач сборки Apache Ant, инструментов командной строки и классов Java. Если вы предпочитаете не использовать Eclipse и плагин, изучите альтернативные возможности, описанные в документации по Java для App Engine.

Загрузите и установите Eclipse с веб-сайта Eclipse. Обязательно загрузите пакет Java EE, содержащий ряд функций, которые пригодятся для разработки веб-приложений.

Чтобы установить плагин Google и SDK App Engine, можно воспользоваться функцией установки программного обеспечения Eclipse.

При работе с Eclipse 3.5 (Galileo) используйте следующий адрес:

http://dl.google.com/eclipse/plugin/3.5

При работе с Eclipse 3.4 (Ganymede) используйте следующий адрес:

http://dl.google.com/eclipse/plugin/3.4

Выберите плагин и SDK App Engine из списка доступного программного обеспечения и установите их. Дополнительную информацию об установке плагина Google для Eclipse можно получить в документации по плагину Google для Eclipse и документации App Engine по плагину.

Создайте проект App Engine следующим образом:

Выберите Файл > Создать > Проект веб-приложения. Вместо этого можно нажать кнопку "Новый проект веб-приложения" на панели инструментов: .
Откроется мастер "Создание проекта веб-приложения". Укажите название в поле "Название проекта", например Parroty. В поле "Пакет" укажите название соответствующего пакета, например parroty.
Поскольку для этого проекта не нужен Google Web Toolkit, снимите флажок "Использовать Google Web Toolkit". Убедитесь, что установлен флажок "Использовать Google App Engine".
Чтобы создать проект, нажмите кнопку Готово.

Мастер создаст структуру каталогов для проекта, включая каталог src/ для файлов с исходным кодом Java и каталог war/ для скомпилированных классов и других файлов приложения, библиотек, файлов конфигурации, статических файлов и прочих файлов данных. Он также создаст файл с исходным кодом сервлета и два файла конфигурации. Полная структура каталогов выглядит следующим образом:

Parroty/
  src/
    parroty/
      server/
        ParrotyServlet.java
    META-INF/
      jdoconfig.xml
    log4j.properties
    logging.properties
  war/
    WEB-INF/
      lib/
        ...App Engine JARs...
      appengine-web.xml
      web.xml
    index.html

Начало работы с App Engine описано в руководстве по началу работы с App Engine для Java.

Hello, Robot!

Чтобы превратить это приложение в робота, потребуется библиотека приложений роботов Java из SDK расширений Google Wave. Кроме того, из этого SDK понадобятся библиотеки JSON. Эти библиотеки представлены в виде следующих JAR:

wave-robot-api.jar
json.jar
jsonrpc.jar

Скопируйте эти файлы из SDK в следующий каталог проекта:

Parroty/war/WEB-INF/lib/

Обновите проект, выбрав в меню Файл > Обновить. Выберите в меню Проект > Свойства, затем в окне "Свойства" выберите каталог "Путь сборки Java". Перейдите на вкладку "Библиотеки" и нажмите кнопку Добавить JAR... Выберите новые JAR и нажмите кнопку ОК. Нажмите кнопку ОК, чтобы закрыть окно "Свойства".

Обработка событий

Чтобы реализовать основной обработчик событий, создайте сервлет, расширяющий класс AbstractRobotServlet (из пакета com.google.wave.api) и реализуйте метод processEvents(), принимающий объект RobotMessageBundle. В этом пакете скомпонованы данные о событиях и связанных с ними волнах. В целях повышения эффективности система Google Wave объединяет события вместе.

В ходе обработки данных в коде API создает список операций, которые должен выполнить Google Wave. По завершении работы метода processEvents() сервлет отправляет эти операции обратно в Google Wave. Класс AbstractRobotServlet отвечает за обработку HTTP-запроса, анализируя данные события, вызывая метод processEvents() и отправляя операции обратно в Google Wave.

Создадим простого робота, который при добавлении в волну отображает в ней приветствие. Помимо этого, добавим другое приветствие, которое показывается при добавлении в волну нового участника. Измените файл src/parroty/ParrotyServlet.java следующим образом:

package com.google.wave.api.samples;

import com.google.wave.api.*;

public class ParrotyServlet extends AbstractRobotServlet {

  @Override
  public void processEvents(RobotMessageBundle bundle) {
    Wavelet wavelet = bundle.getWavelet();
	      
    if (bundle.wasSelfAdded()) {
      Blip blip = wavelet.appendBlip();
      TextView textView = blip.getDocument();
      textView.append("I'm alive!");
    }
	    
    for (Event e: bundle.getEvents()) {
      if (e.getType() == EventType.WAVELET_PARTICIPANTS_CHANGED) {    
        Blip blip = wavelet.appendBlip();
        TextView textView = blip.getDocument();
        textView.append("Hi, everybody!");
      }
    }
  }
}

Метод processEvents() класса ParrotyServlet принимает объект RobotMessageBundle и вызывает удобный метод, чтобы проверить, является ли хотя бы одно из событий в пакете добавляемым в вейвлет роботом. Если да, выполняется получение вейвлета и создание нового всплеска в конце вейвлета. Робот получает доступ к новому документу всплеска и добавляет приветствие.

Кроме того, метод processEvents() просматривает все события в пакете RobotMessageBundle и проверяет, нет ли среди них событий типа WAVELET_PARTICIPANTS_CHANGED. Если да, то робот добавляет специальное приветствие.

Две эти техники демонстрируют различные способы обработки событий: использование удобного метода в API и просмотр отдельных событий.

Сопоставление сервлета

Чтобы установить соответствие этого сервлета с URL /_wave/robot/jsonrpc, измените файл war/WEB-INF/web.xml следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <servlet>
        <servlet-name>Parroty</servlet-name>
        <servlet-class>parroty.ParrotyServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>Parroty</servlet-name>
        <url-pattern>/_wave/robot/jsonrpc</url-pattern>
    </servlet-mapping>
</web-app>

Создание файла конфигурации

Этому роботу нужен файл конфигурации, чтобы показать Google Wave, что он является роботом и заинтересован в новых участниках. В обозревателе пакетов создайте папку war/_wave/, а в ней – файл capabilities.xml следующего содержания:

<?xml version="1.0" encoding="utf-8"?>
<w:robot xmlns:w="http://wave.google.com/extensions/robots/1.0">
  <w:capabilities>
    <w:capability name="WAVELET_PARTICIPANTS_CHANGED" content="true" />
    <w:capability name="WAVELET_SELF_ADDED" content="true" /> 
  </w:capabilities>
  <w:version>1</w:version>
</w:robot>

(Чтобы вводить XML в виде текста в Eclipse, может потребоваться перейти на вкладку "Исходный код" внизу окна редактора.)

В этом файле конфигурации предусмотрены две возможности робота: распознавание событий типов WAVELET_PARTICIPANTS_CHANGED и WAVELET_SELF_ADDED. Если эти события происходят в вейвлете, в котором участвует этот робот, Google Wave обратится к роботу с содержанием этого вейвлета (content="true").

Обратите внимание, что это будет происходить в случае любых изменений участников вейвлетов, за исключением добавления самого робота. По этой причине мы зарегистрируем отдельное событие WAVELET_SELF_ADDED, которое робот точно получит при добавлении в волну. Это событие может служить событием инициализации. Робот может отслеживать вейвлеты, в которых он участвует, сохраняя и удаляя идентификаторы вейвлетов (такие как в хранилище данных App Engine) в случае изменения участников.

Версии роботов

Роботам в API Google Wave присваиваются версии. Это позволяет системе Google Wave определить изменение роботов и их возможностей. Изменив возможности робота (например, добавив или удалив отслеживаемые события), необходимо также изменить идентификатор его версии в файле робота capabilities.xml.

При развертывании робота система Google Wave сравнит его идентификатор со значением в кэше. (Идентификатор робота представляет собой обычную текстовую строку.) Если так, Google Wave обновит файл capabilities.xml и систему, которая создаст отслеживаемые события.

Развертывание робота

Чтобы проверить робота, разверните его в App Engine и добавьте в волну.

Примечание. В настоящее время не существует механизма для проверки Wave-роботов на локальном компьютере с помощью сервера разработки App Engine. В будущем выпуске SDK Google Wave будет предусмотрена возможность локальной проверки роботов до их развертывания в App Engine.

Измените файл war/WEB-INF/appengine-web.xml в Eclipse. В элементе <application> укажите зарегистрированный идентификатор приложения. Например, если зарегистрирован идентификатор приложения parrotybot, то файл appengine-web.xml может выглядеть следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
	<application>parrotybot</application>
	<version>1</version>
</appengine-web-app>

Чтобы развернуть приложение в App Engine, нажмите кнопку "Развернуть в App Engine" на панели инструментов Eclipse: . При появлении запроса введите адрес электронной почты и пароль. Eclipse соберет проект и добавит его в App Engine.

Чтобы убедиться в доступности приложения, перейдите по следующему URL-адресу:

http://applicationName.appspot.com/_wave/capabilities.xml

В результате должен быть получен XML-файл с возможностями, аналогичный следующему:

Чтобы проверить приложение в App Engine, войдите на сайт https://appengine.google.com/

Добавление робота в волну

Робот добавляется в волну, с которой нужно взаимодействовать, в качестве участника. Чтобы сделать это, необходимо сначала добавить адрес робота в существующие контакты. (На данный момент это нужно делать вне текущей волны.)

Теперь создайте волну в Google Wave. Добавьте робота в волну, используя его идентификатор Google Wave, который представлен в виде идентификатора приложения App Engine с @appspot.com (например, dummyrobot@appspot.com). Робот присоединится к волне и добавит приветствие.

Поздравляем! Вы создали своего первого Wave-робота!