From 7ee85f011a2060684904be37cf37eddbe2606c32 Mon Sep 17 00:00:00 2001 From: symphony-thibault Date: Tue, 29 Sep 2020 15:35:59 +0200 Subject: [PATCH 1/2] APP-3083 Core SpringBoot Starter documentation --- docs/getting-started-spring.md | 2 - docs/index.md | 8 +- docs/spring-boot/core-starter.md | 257 +++++++++++++++++++++++++++++++ 3 files changed, 263 insertions(+), 4 deletions(-) delete mode 100644 docs/getting-started-spring.md create mode 100644 docs/spring-boot/core-starter.md diff --git a/docs/getting-started-spring.md b/docs/getting-started-spring.md deleted file mode 100644 index 6996af7ad..000000000 --- a/docs/getting-started-spring.md +++ /dev/null @@ -1,2 +0,0 @@ -# Getting Started with Symphony BDK for SpringBoot - diff --git a/docs/index.md b/docs/index.md index fe784b648..833a75c9e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # Symphony BDK Reference Documentation -This reference guide provides detailed information about the Symphony BDK. It provides comprehensive -documentation for all features and abstractions made on top of the [Symphony REST API](https://developers.symphony.com/restapi/reference). +This reference guide provides detailed information about the Symphony BDK. It provides a comprehensive documentation +for all features and abstractions made on top of the [Symphony REST API](https://developers.symphony.com/restapi/reference). If you are just getting started with Symphony Bot developments, you may want to begin reading the [Getting Started](./getting-started.md) guide. @@ -17,3 +17,7 @@ The reference documentation consists of the following sections: | [Message API](message.md) | Sending or searching messages, usage of templates | | [Activity API](activity-api.md) | The Activity Registry, creating custom activities | +### Spring Boot +Getting Started guides are also available for Spring Boot: +- [Core Starter](./spring-boot/core-starter.md) + diff --git a/docs/spring-boot/core-starter.md b/docs/spring-boot/core-starter.md new file mode 100644 index 000000000..51e123e6b --- /dev/null +++ b/docs/spring-boot/core-starter.md @@ -0,0 +1,257 @@ +# BDK Core SpringBoot Starter +The Symphony BDK for Java provides a _Starter_ module that aims to ease bot developments within a +[Spring Boot](https://spring.io/projects/spring-boot) application. + +## Features +- Configure bot environment through `application.yaml` +- Subscribe to Real Time Events from anywhere +- Provide injectable services +- Ease activities creation +- Provide `@Slash` annotation to register a [slash command](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core/latest/com/symphony/bdk/core/activity/command/SlashCommand.html) + +## Installation + +The following listing shows the `pom.xml` file that is created when you choose Maven: +```xml + + + 4.0.0 + + com.example + bdk-core-spring-boot + 0.0.1-SNAPSHOT + bdk-core-spring-boot + + + + com.symphony.platformsolutions + symphony-bdk-core-spring-boot-starter + 1.3.0.BETA + + + +``` +The following listing shows the `build.gradle` file that is created when you choose Gradle: +```groovy +plugins { + id 'org.springframework.boot' version "2.3.3.RELEASE" +} + +dependencies { + implementation 'org.springframework.boot:spring-boot-starter:1.3.0.BETA' +} +``` + +## Create a Simple Bot Application +As a first step, you have to initialize your bot environment through the Spring Boot `src/main/resources/application.yaml` file: +```yaml +bdk: + host: acme.symphony.com + bot: + username: bot-username + privateKeyPath: /path/to/rsa/privatekey.pem +``` +> You can notice here that the `bdk` property inherits from the [`BdkConfig`](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core/latest/com/symphony/bdk/core/config/model/BdkConfig.html) class. + +As required by Spring Boot, you have to create an `src/main/java/com/example/bot/BotApplication.java` class: +```java +@SpringBootApplication +public class BotApplication { + + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } +} +``` + +Now you can create a component for a simple bot application, as the following listing (from `src/main/java/com/example/bot/HelloBot.java`) +shows: +```java +@Component +public class HelloBot { + + @Autowired + private MessageService messageService; + + @EventListener + public void onMessageSent(RealTimeEvent event) { + this.messageService.send(event.getSource().getMessage().getStream(),"Hello!"); + } +} +``` + +You can finally run your Spring Boot application and verify that your bot always replies with `Hello!`. + +## Subscribe to Real Time Events +The Core Starter uses [Spring Events](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/ApplicationEventPublisher.html) +to deliver Real Time Events. + +You can subscribe to any Real Time Event from anywhere in your application by creating a handler method that has to +respect two conditions: +- be annotated with [@EventListener](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/event/EventListener.html) +- have `com.symphony.bdk.spring.events.RealTimeEvent` parameter + +Here's the list of Real Time Events you can subscribe: +```java +@Component +public class RealTimeEvents { + + @EventListener + public void onMessageSent(RealTimeEvent event) {} + + @EventListener + public void onSharedPost(RealTimeEvent event) {} + + @EventListener + public void onInstantMessageCreated(RealTimeEvent event) {} + + @EventListener + public void onRoomCreated(RealTimeEvent event) {} + + @EventListener + public void onRoomUpdated(RealTimeEvent event) {} + + @EventListener + public void onRoomDeactivated(RealTimeEvent event) {} + + @EventListener + public void onRoomReactivated(RealTimeEvent event) {} + + @EventListener + public void onUserRequestedToJoinRoom(RealTimeEvent event) {} + + @EventListener + public void onUserJoinedRoom(RealTimeEvent event) {} + + @EventListener + public void onUserLeftRoom(RealTimeEvent event) {} + + @EventListener + public void onRoomMemberPromotedToOwner(RealTimeEvent event) {} + + @EventListener + public void onRoomMemberDemotedFromOwner(RealTimeEvent event) {} + + @EventListener + public void onConnectionRequested(RealTimeEvent event) {} + + @EventListener + public void onConnectionAccepted(RealTimeEvent event) {} + + @EventListener + public void onMessageSuppressed(RealTimeEvent event) {} + + @EventListener + public void onSymphonyElementsAction(RealTimeEvent event) {} +} +``` + +## Inject Services +The Core Starter injects services within the Spring application context: +```java +@Service +public class CoreServices { + + @Autowired + private MessageService messageService; + + @Autowired + private StreamService streamService; + + @Autowired + private UserService userService; + + @Autowired + private DatafeedService datafeedService; + + @Autowired + private SessionService sessionService; + + @Autowired + private ActivityRegistry activityRegistry; +} +``` +> Please note that field injection is not recommended, you should consider using +> [_Constructor-based DI_](https://docs.spring.io/spring-framework/docs/4.2.x/spring-framework-reference/html/beans.html#beans-constructor-injection) +> instead. + +## Slash Command +You can easily register a slash command using the `@Slash` annotation. Note that the `CommandContext` is mandatory to +successfully register your command. If not defined, a `warn` message will appear in your application log. + +```java +@Component +public class SlashHello { + + @Slash("/hello") + public void onHello(CommandContext commandContext) { + log.info("On /hello command"); + } + + @Slash(value = "/hello", mentionBot = false) + public void onHelloNoMention(CommandContext commandContext) { + log.info("On /hello command (bot has not been mentioned)"); + } +} +``` +By default, the `@Slash` annotation is configured to require bot mention in order to trigger the command. You can override +this value using `@Slash#mentionBot` annotation parameter. + +## Activities +> For more details about activities, please read the [Activity API reference documentation](../activity-api.md) + +Any service or component class that extends [`FormReplyActivity`](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core/latest/com/symphony/bdk/core/activity/form/FormReplyActivity.html) +or [`CommandActivity`](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core/latest/com/symphony/bdk/core/activity/command/CommandActivity.html) +will be automatically registered within the [ActivityRegistry](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core/latest/com/symphony/bdk/core/activity/ActivityRegistry.html). + +The following example demonstrates how to send an Elements form on `@BotMention /gif` slash command. The Elements form +located in `src/main/resources/templates/gif.ftl` contains: +```xml + +

Gif Generator

+
+ + + + + + + +
 +``` + +```java +@Slf4j +@Component +public class GifFormActivity extends FormReplyActivity { + + @Autowired + private MessageService messageService; + + @Slash("/gif") + public void displayGifForm(CommandContext context) throws TemplateException { + this.messageService.send(context.getStreamId(), "/templates/gif.ftl", emptyMap()); + } + + @Override + public ActivityMatcher matcher() { + return context -> "gif-category-form".equals(context.getFormId()) + && "submit".equals(context.getFormValue("action")) + && StringUtils.isNotEmpty(context.getFormValue("category")); + } + + @Override + public void onActivity(FormReplyContext context) { + log.info("Gif category is \"{}\"", context.getFormValue("category")); + } + + @Override + protected ActivityInfo info() { + return new ActivityInfo().type(ActivityType.FORM) + .name("Gif Display category form command") + .description("\"Form handler for the Gif Category form\""); + } +} +``` From db1d33f19d9328413465c32a340b97765f980ba1 Mon Sep 17 00:00:00 2001 From: symphony-thibault Date: Wed, 30 Sep 2020 15:22:44 +0200 Subject: [PATCH 2/2] APP-3083 Fixed review comments --- docs/spring-boot/core-starter.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/spring-boot/core-starter.md b/docs/spring-boot/core-starter.md index 51e123e6b..9fc9e148b 100644 --- a/docs/spring-boot/core-starter.md +++ b/docs/spring-boot/core-starter.md @@ -1,4 +1,4 @@ -# BDK Core SpringBoot Starter +# BDK Core Spring Boot Starter The Symphony BDK for Java provides a _Starter_ module that aims to ease bot developments within a [Spring Boot](https://spring.io/projects/spring-boot) application. @@ -11,7 +11,7 @@ The Symphony BDK for Java provides a _Starter_ module that aims to ease bot deve ## Installation -The following listing shows the `pom.xml` file that is created when you choose Maven: +The following listing shows the `pom.xml` file that has to be created when using Maven: ```xml ``` -The following listing shows the `build.gradle` file that is created when you choose Gradle: +The following listing shows the `build.gradle` file that has to be created when using Gradle: ```groovy plugins { id 'org.springframework.boot' version "2.3.3.RELEASE" @@ -77,7 +77,7 @@ public class HelloBot { @EventListener public void onMessageSent(RealTimeEvent event) { - this.messageService.send(event.getSource().getMessage().getStream(),"Hello!"); + this.messageService.send(event.getSource().getMessage().getStream(), "Hello!"); } } ``` @@ -173,9 +173,6 @@ public class CoreServices { private ActivityRegistry activityRegistry; } ``` -> Please note that field injection is not recommended, you should consider using -> [_Constructor-based DI_](https://docs.spring.io/spring-framework/docs/4.2.x/spring-framework-reference/html/beans.html#beans-constructor-injection) -> instead. ## Slash Command You can easily register a slash command using the `@Slash` annotation. Note that the `CommandContext` is mandatory to