APP-3060 Documentation revamping, getting started

README.md

@@ -1,43 +1,54 @@
-# Symphony Java BDK 
+# Symphony BDK for Java 
 [![CircleCI](https://circleci.com/gh/SymphonyPlatformSolutions/symphony-api-client-java.svg?style=shield)](https://circleci.com/gh/SymphonyPlatformSolutions/symphony-api-client-java)
 [![Known Vulnerabilities](https://snyk.io/test/github/SymphonyPlatformSolutions/symphony-api-client-java/badge.svg)](https://snyk.io/test/github/SymphonyPlatformSolutions/symphony-api-client-java)
-[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-api-client-java/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-api-client-java)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-bdk-bom/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.symphony.platformsolutions/symphony-api-client-java)
+[![javadoc](https://javadoc.io/badge2/com.symphony.platformsolutions/symphony-bdk-core/javadoc.svg)](https://javadoc.io/doc/com.symphony.platformsolutions/symphony-bdk-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
 [![Email](https://img.shields.io/static/v1?label=contact&message=email&color=darkgoldenrod)](mailto:platformsolutions@symphony.com?subject=Java%20SDK)
 
-The Symphony Java BDK helps you to create Bots and Applications on top of the [Symphony REST APIs](https://developers.symphony.com/restapi/reference). 
-
-Documentation about BDK features and usage is available under [docs](./docs/index.md) folder.
-
-## How to Build
-
-As this project contains modules for the legacy SDK/BDK as well as for the 2.0 ones, some
-Maven are defined to make the build faster depending on which version you are working on.
-
-The BDK can be built and published to your local Maven cache using the [Maven Wrapper](https://github.com/takari/maven-wrapper). 
+The Symphony BDK for Java helps you to create production-grade Chat Bots and Extension Applications on 
+top of the [Symphony REST APIs](https://developers.symphony.com/restapi/reference). 
+
+## Installation and Getting Started
+The [reference documentation](./docs/index.md) includes detailed installation instructions as well as a comprehensive 
+[getting started](./docs/getting-started.md) guide.
+
+Here is a quick teaser of a complete Symphony BDK application in Java:
+```java
+public class BotApplication {
+
+    public static void main(String[] args) {
+
+        final SymphonyBdk bdk = new SymphonyBdk(BdkConfigLoader.loadFromSymphonyDir("config.yaml"));
+
+        bdk.activities().register(new SlashCommand("/hello", context -> {
+            bdk.messages().send(context.getStreamId(), "<messageML>Hello, World!</messageML>");
+        }));
+
+        bdk.datafeed().start();
+    }
+}
+```
 
-**Build Legacy Modules**
+## Build from Source
+The Symphony BDK uses a [Maven](https://maven.apache.org/) build. The instructions below use the [Maven Wrapper](https://github.com/takari/maven-wrapper)
+from the root of the source tree. The wrapper script serves as a cross-platform, self-contained bootstrap mechanism for
+the build system.
 
-The `legacy` profile is activated by default so there is no specific argument to define to have
-it part of the build. However, it is also possible to skip legacy modules to be built using argument `-P -legacy`:
+### Before you start
+To build you will need [Git](https://docs.github.com/en/github/getting-started-with-github/set-up-git) and [JDK 8 or later](https://adoptopenjdk.net/).
+Be sure that your `JAVA_HOME` environment variable points to the `jdk1.8+` folder extracted from the JDK download.
 
+### Build from the Command Line
+To compile, test and build all jars, use:
 ```shell script
-# build the legacy modules
-./mvnw clean install
-
-# skip building legacy modules
-./mvnw clean install -P -legacy
+./mvnw clean package
 ```
-
-**Build BDK 2.0 Modules**
-
-Still in construction, the 2.0 modules are deactivated by default but can be activated through the Maven profile `2.0` : 
-
+### Install in local Maven repository
+To install all Symphony BDK jars in your local Maven repository, use:
 ```shell script
-# build the 2.0 modules only, skip the legacy ones
-./mvnw clean install -P2.0,-legacy
+./mvnw clean install
 ```
 
 ## License
-
 The Symphony BDK is Open Source software released under the [MIT License](./LICENSE).

docs/activity.md → docs/activity-api.md

@@ -178,3 +178,6 @@ class HelloFormReplyActivity extends FormReplyActivity<FormReplyContext> {
 1. The `ActivityMatcher` ensures that activity logic is triggered only when the form with `id` "**hello-form**" has been 
 submitted from the action button "**submit**"
 2. The activity context allows to directly retrieve form values. Here the "**name**" `<text-field>` value
+
+----
+[Home :house:](./index.md)

docs/authentication.md

@@ -24,3 +24,6 @@ public class Example {
 }
 
 ```
+
+----
+[Home :house:](./index.md)

docs/configuration.md

@@ -1,79 +1,53 @@
 # Configuration
 
-The BDK configuration is one of the most basic feature of the BDK project which help
-developers configure their own bot.
+The BDK configuration is one of the most essential feature of the Symphony BDK which allows developers to configure 
+their bot environment.
 
-## Configuration structure
-
-The BDK configuration now includes the following properties:
-- The BDK configuration can contain the global properties for `host`, `port`, `context` and `scheme`. 
-These global properties can be used by the client configuration by default or can be override if
-user specify the dedicated `host`, `port`, `context`, `scheme` inside the client configuration.
-- `pod` contains information like host, port, scheme, context, proxy... of the pod on which 
-the service account using by the bot is created.
-- `agent` contains information like host, port, scheme, context, proxy... of the agent which 
-the bot connects to.
-- `keyManager` contains information like host, port, scheme, context, proxy... of the key 
-manager which manages the key token of the bot.
-- `bot` contains information about the bot like the username, the private key or 
-the certificate for authenticating the service account on pod.
-- `app` contains information about the extension app that the bot will use like 
-the appId, the private key or the certificate for authenticating the extension app.
-- `ssl` contains trustStore and trustStore password for SSL communication.
-- `datafeed` contains information of the datafeed service to be used by the bot.
-- `retry` contains information for retry mechanism to be used by the bot.
-
-### Retry Configuration
-The retry mechanism used by the bot will be configured by these following properties:
-- `maxAttempts`: maximum number of retry attempts that the bot is able to make.
-- `multiplier`: after each attempt, the interval between two attempts will be multiplied by 
-this factor. (Exponential backoff strategy)
-- `initialIntervalMillis`: the initial interval between two attempts.
-- `maxIntervalMillis`: the limit of the interval between two attempts. For example: if the 
-current interval is 1000 millis, multiplier is 2.0 and the maxIntervalMillis is 1500 millis,
-then the interval for next retry will be 1500 millis.
-
-Each bot will have a global retry configuration to be used in every services with the following
-default value:
-- `maxAttempts`: 10
-- `initialIntervalMillis`: 500
-- `multiplier`: 2
-- `maxIntervalMillis`: 300000 (5 mins)
-
-This global retry configuration can be override by each service. We can define a specific retry 
-configuration inside service configuration to override the global one.
-
-### DatafeedConfiguration
-The datafeed configuration will contain information about the datafeed service to be used by the bot:
-- `version`: the version of datafeed service to be used. By default, the bot will use the datafeed v1
-service. 
-- `idFilePath`: the path to the file which will be used to persist a created datafeed id in case the 
-datafeed service v1 is used.
-- `retry`: the specific retry configuration can be used to override the global retry configuration. If no
-retry configuration is defined, the global one will be used.
-
-## Configuration format
-
-Both of `JSON` and `YAML` formats are supported by BDK configuration. 
-
-## Configuration usage
-
-BDK configuration can be read:
-- From a file: `BdkConfigLoader#loadFromFile` giving the path to the configuration file.
-- From an InputStream: `BdkConfigLoader#loadFromInputStream` giving the input stream
-of the configuration file.
-- From a classpath: `BdkConfigLoader#loadFromClasspath` giving the classpath to the
-configuration file.
-
-The configuration file after being read will be represented by `BdkConfig` class which contains:
-
-- The configuration for `pod`, `agent`, `keyManager`is represented by `BdkClientConfig`.
-- The configuration for `bot` is represented by `BdkBotConfig`.
-- The configuration for `app` is represented by `BdkExtAppConfig`.
-- The configuration for `ssl` is represented by `BdkSslConfig`.
-
-## BDK configuration example
+## Minimal configuration example
+The minimal configuration file that can be provided look like:
+```yaml
+host: acme.symphony.com                                     # (1)
 
+bot: 
+    username: bot-username                                  # (2)
+    privateKeyPath: /path/to/bot/rsa-private-key.pem        # (3)
+```
+1. hostname of your Symphony pod environment
+2. your bot (or service account) username as configured in your pod admin console (https://acme.symphony.com/admin-console)
+3. your bot RSA private key according to the RSA public key upload in your pod admin console (https://acme.symphony.com/admin-console)
+
+## How to load configuration
+The Symphony BDK provides a single way to configure your bot environment. 
+
+```java
+public class Example {
+
+    public static void main(String[] args) {
+
+      final BdkConfig config01 = BdkConfigLoader.loadFromFile("/absolute/path/to/config.yaml");             // (1)
+      final BdkConfig config02 = BdkConfigLoader.loadFromClasspath("/config.yaml");                         // (2)
+
+      final InputStream configInputStream = new FileInputStream(new File("/absolute/path/to/config.yaml"));
+      final BdkConfig config03 = BdkConfigLoader.loadFromInputStream(configInputStream);                    // (3)
+
+      final BdkConfig config04 = BdkConfigLoader.loadFromSymphonyDir("config.yaml");                        // (4)
+
+      final BdkConfig config05 = new BdkConfig();                                                           // (5)
+      configAsPojo.setHost("acme.symphony.com");
+      configAsPojo.getBot().setUsername("bot-username");
+      configAsPojo.getBot().setPrivateKeyPath("/path/to/bot/rsa-private-key.pem");
+    }
+}
+```
+1. Load configuration from a system location path
+2. Load configuration from a classpath location
+3. Load configuration from an [`InputStream`](https://docs.oracle.com/javase/7/docs/api/java/io/InputStream.html)
+4. Load configuration from the Symphony directory. The Symphony directory is located under your `${user.home}/.symphony` 
+    folder. It can be useful when you don't want to share your own Symphony credentials within your project codebase
+5. Last but not least, you can obviously define your configuration object as a [POJO](https://en.wikipedia.org/wiki/Plain_old_Java_object) 
+    and load it from any external system
+
+## Full configuration example
 ```yaml
 scheme: https
 host: localhost.symphony.com
@@ -96,7 +70,7 @@ sessionAuth:
 
 bot:
   username: bot-name
-  privateKeyPath: path/to/private-key.pem
+  privateKeyPath: /path/to/bot/rsa-private-key.pem
   certificatePath: /path/to/bot-certificate.p12
   certificatePassword: changeit
 
@@ -121,12 +95,80 @@ retry:
   initialIntervalMillis: 2000
   multiplier: 1.5
   maxIntervalMillis: 10000
+```
+
+### Configuration structure
 
+The BDK configuration now includes the following properties:
+- The BDK configuration can contain the global properties for `host`, `port`, `context` and `scheme`. 
+These global properties can be used by the client configuration by default or can be override if
+user specify the dedicated `host`, `port`, `context`, `scheme` inside the client configuration.
+- `pod` contains information like host, port, scheme, context, proxy... of the pod on which 
+the service account using by the bot is created.
+- `agent` contains information like host, port, scheme, context, proxy... of the agent which 
+the bot connects to.
+- `keyManager` contains information like host, port, scheme, context, proxy... of the key 
+manager which manages the key token of the bot.
+- `bot` contains information about the bot like the username, the private key or 
+the certificate for authenticating the service account on pod.
+- `app` contains information about the extension app that the bot will use like 
+the appId, the private key or the certificate for authenticating the extension app.
+- `ssl` contains trustStore and trustStore password for SSL communication.
+- `datafeed` contains information of the datafeed service to be used by the bot.
+- `retry` contains information for retry mechanism to be used by the bot.
+
+#### Retry Configuration
+The retry mechanism used by the bot will be configured by these following properties:
+- `maxAttempts`: maximum number of retry attempts that the bot is able to make.
+- `multiplier`: after each attempt, the interval between two attempts will be multiplied by 
+this factor. (Exponential backoff strategy)
+- `initialIntervalMillis`: the initial interval between two attempts.
+- `maxIntervalMillis`: the limit of the interval between two attempts. For example: if the 
+current interval is 1000 millis, multiplier is 2.0 and the maxIntervalMillis is 1500 millis,
+then the interval for next retry will be 1500 millis.
+
+Each bot will have a global retry configuration to be used in every services with the following
+default value:
+- `maxAttempts`: 10
+- `initialIntervalMillis`: 500
+- `multiplier`: 2
+- `maxIntervalMillis`: 300000 (5 mins)
+
+This global retry configuration can be override by each service. We can define a specific retry 
+configuration inside service configuration to override the global one.
+
+#### DatafeedConfiguration
+The datafeed configuration will contain information about the datafeed service to be used by the bot:
+- `version`: the version of datafeed service to be used. By default, the bot will use the datafeed v1
+service. 
+- `idFilePath`: the path to the file which will be used to persist a created datafeed id in case the 
+datafeed service v1 is used.
+- `retry`: the specific retry configuration can be used to override the global retry configuration. If no
+retry configuration is defined, the global one will be used.
+
+## Configuration format
+Both of `JSON` and `YAML` formats are supported by BDK configuration. Using `JSON`, a minimal configuration file would 
+look like: 
+```json
+{
+  "host": "acme.symphony.com",
+  "bot": { 
+    "username": "bot-username",
+    "privateKeyPath": "/path/to/bot/rsa-private-key.pem"
+  }
+}
+``` 
+Reading a `JSON` configuration file is completely transparent: 
+```java
+final BdkConfig config = BdkConfigLoader.loadFromClasspath("/config.json")
 ```
 
-## Backward Compatibility with legacy configuration file  
+## Backward Compatibility with legacy configuration file (experimental) 
 
 The legacy configuration using by the Java SDK v1 is also supported in BDK Configuration 2.0.
 
 This legacy configuration can be also read from a file, an inputstream, a classpath and automatically
 translated to `BdkConfig` instance.
+
+----
+[Home :house:](./index.md)

docs/fluent.md → docs/fluent-api.md

@@ -49,3 +49,5 @@ that is available in BDK is:
 - Datafeed Service: `bdk.datafeed()`
 - Activities Registry: `bdk.activities()`
 
+----
+[Home :house:](./index.md)