-
Notifications
You must be signed in to change notification settings - Fork 40
Как создать модуль
Прежде чем приступать к созданию модулей, внимательно ознакомьтесь с описанием архитектуры Агрегата. Без этих вводных знаний трудно понять, что написано в этом разделе.
Модуль - это по сути verticle в терминах Vertx. То есть любой модуль должен быть написан и упакован ровно так же, как пишется и упаковывается любой модуль в Vertx. Подробнее о том, как выглядит модуль Vertx на Java, читайте здесь. В документации Vertx можно найти подробную документацию и для других языков программирования - в разделе Core на этой странице.
Вы можете использовать один из поддерживаемых языков программирования и любую удобную для вас IDE для разработки. Агрегат не накладывает никаких ограничений ни на IDE, ни на способ реализации модуля, ни на сторонние библиотеки, которые ему могут понадобиться.
Любой модуль (неважно какого типа) - это простой архив (в случае с Java это jar архив), который содержит нужный код (в случае с Java скомпилированный байткод, в случае JavaScript просто исходники). Также в архиве должен присутствовать текстовый файл-дескриптор с именем <имя модуля>.json, где указан обязательный параметр main, указывающий на главный исполняющий файл вашего модуля. Например:
{
"main" : "com.aggregate.detector.key.KeyDetector"
}Указывает, что при старте модуля Агрегат должен запустить класс com.aggregate.detector.key.KeyDetector вашего модуля. При этом сам модуль может конечно же содержать гораздо больше файлов и классов, но минимум один.
О том, что такое файл-дескриптор и что в нем можно писать, читайте в документации Vertx.
Имя модуля должно совпадать с именем файла модуля. Так чтобы Агрегат использовал его как имя сервиса в терминах Vertx. Для модулей Java, собранных с помощью Maven, имя файла модуля может также содержать номер версии. Например key-detector-1.0.0.jar
Все что необходимо вашему модулю. В случае если вы создаете функциональный голосовой модуль, то в архиве еще должен присутствовать файл грамматики голосовых запросов с именем <имя модуля>.xml, который содержит шаблоны команд и описание диалоговых контекстов. Подробнее о нем читайте в разделе Функциональный модуль.
Если вы пишете на Java, то самый простой способ для разработки и сборки модуля - это использовать Maven. Установите его, а в файле pom.xml вашего модуля пропишите нужные вам зависимости, название модуля и его версию. Например:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.aggregate</groupId>
<artifactId>date-time</artifactId>
<version>1.0.0</version>
<distributionManagement>
<repository>
<id>bintray-aggregate</id>
<url>https://api.bintray.com/maven/uzyovoys/aggregate/date-time/;publish=1</url>
</repository>
</distributionManagement>
<repositories>
<repository>
<id>bintray-aggregate</id>
<url>https://dl.bintray.com/uzyovoys/aggregate</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.aggregate</groupId>
<artifactId>api</artifactId>
<version>0.0.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-core</artifactId>
<version>3.2.1</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<finalName>${artifactId}</finalName>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.3</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</build>
</project>Обязательной является только зависимость vertx-core. Указывайте ее scope provided всегда. Если вам нужен и API Агрегата (только для функциональных модулей), то укажите зависимость от api (как в примере выше) и тоже укажите что она provided. Не забудьте в этом случае добавить репозиторий https://dl.bintray.com/uzyovoys/aggregate, так как API Агрегата пока нет в центральном репозитории Maven.
Если ваш модуль имеет другие зависимости, то обязательно включайте их классы в сборку с помощью следующего плагина:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>1.6</version>
<configuration>
<createDependencyReducedPom>true</createDependencyReducedPom>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>После этого вы можете собирать ваш модуль простой командой в консоли mvn clean install.
Понятно, что во время разработки модуля может потребоваться отладка. Для этого запустите Агрегат с помощью одного из скриптов, в имени которого есть слово debug. Для Windows - start_debug.bat, для Mac OS и Linux - start_debug.sh. Этот скрипт запустит Java с открытым портом 5555 для подключения к нему отладчика.
В вашей IDE вы можете легко нему подключиться, чтобы отлаживать ваш код. Например в IntelliJ IDEA создайте новую конфигурацию запуска приложения типа "Remote" и укажите там подключение к порту 5555 на localhost.
После запуска вы можете увидеть в консоли, что ваша IDE подключилась к Агрегату и теперь можно ставить breakpoint и работать с дебагером.
Чтобы не проходить каждый раз процедуру копирования вашей сборки модуля в папку deploy, просто используйте команду mvn clean install и перезапускайте Агрегат. Он сразу подхватит последнюю версию вашего модуля и установит ее.
Вы можете создать:
- функциональный модуль (который будет понимать голосовые команды пользователя)
- модуль активации (как например активация с клавиатуры)
- модуль распознавания речи (который слушает команду и превращает ее в текст для Агрегата)
- модуль синтеза речи (воспроизводит текст ответа Агрегата в виде речи)
Каждый модуль волен реализовывать свою функциональность так, как это ему требуется. Но есть некоторая общая структура, которая диктуется фреймворком Vertx.
Если вы пишете модуль на Java, то ваш главный класс должен расширять абстрактный класс io.vertx.core.AbstractVerticle из фреймворка Vertx.
Главный файл модуля должен иметь метод start. Он вызывается фреймворком при старте модуля. Существует два вида этого метода - синхронный и асинхронный. Первый нужно использовать, если процедура инициализации модуля быстрая и не связана с трудоемкими операциями. Второй нужен в обратном случае. Вот примеры на языке Java.
@Override
public void start() throws Exception {
vertx.eventBus().consumer("cmd.datetime.time", m -> {
m.reply(getTime());
});
}Здесь мы просто зарегистрировали слушателя на нужное нам событие. Это быстрая операция, поэтому можно использовать синхронный вариант. Если нужно сообщить об ошибке в таком методе, то нужно просто выбросить исключение любого типа с текстом ошибки.
@Override
public void start(Future<Void> f) throws Exception {
String accessKey = config().getString("accessKey");
String secretKey = config().getString("secretKey");
if (accessKey == null || accessKey.isEmpty() || secretKey == null || secretKey.isEmpty()) {
f.fail("Provide your access and secret keys in config file");
return;
}
BasicAWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey);
client = new IvonaSpeechCloudClient(new StaticCredentialsProvider(credentials));
client.setEndpoint(ENDPOINT);
vertx.eventBus().consumer("tts.say", msg -> {
...
});
f.complete();
}Здесь происходит создание клиента для стороннего сервиса, что может занять время, поэтому используется асинхронный вид старта. В этом случае модуль обязан вызвать на объекте Future либо метод fail в случае ошибки, либо complete в случае удачного старта.
Также можно получить конфигурацию модуля, который Агрегат предоставит ему при старте (это тот самый файл <имя модуля>.json в папке conf). Для этого можно вызывать метод config(), который вернет JSON объект конфигурации. А уже оттуда можно вытаскивать данные по известным модулю именам.
Вообще это можно делать в любом методе модуля, но только после того, как вызван метод start или в самом этом методе.
Если модуль останавливается Агрегатом (при выгрузке модуля или при остановке самого Агрегата), то будет вызван метод stop. Там можно освободить используемые ресурсы (если такие есть) и правильно завершить работу модуля.
Так же, как и для метода start, для данного метода существуют синхронная и асинхронная версии.
Sorry, there was an error rendering this page.