diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 852c92bee..984c69087 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ New feature requests on the legacy SDK will not be accepted. This repository contains both the legacy Java SDK under the [symphony-bdk-legacy module](symphony-bdk-legacy) and the BDK2.0 under all other root modules. Please check the [legacy module readme file](symphony-bdk-legacy/README.md) and the -[BDK2.0 architecture file](docs/internal/bdk-architecture.md) for more information. +[BDK architecture](docs/tech/architecture.md) documentation for more information. ## Testing diff --git a/docs/index.md b/docs/index.md index 833a75c9e..0f885a56a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,3 +21,5 @@ The reference documentation consists of the following sections: Getting Started guides are also available for Spring Boot: - [Core Starter](./spring-boot/core-starter.md) +### Technical Documentation +You can find an overview of the BDK Architecture [here](./tech/architecture.md). diff --git a/docs/internal/bdk-architecture.md b/docs/internal/bdk-architecture.md deleted file mode 100644 index c1716083a..000000000 --- a/docs/internal/bdk-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# BDK2.0 - Project Architecture - -The BDK project is composed in a set of different modules. The approach consists in having one module per BDK -"layer". - -## The layers - -The BDK is divided in 3 different layers: -- `core` that contains the minimal set of classes to configure, authenticate and use -the main APIs -- `advanced` that contains additional features on top of the core module such as the -command API, the template API or even an NLP integration -- `framework` that provides connectors (or starters) for the main Java frameworks -such as [SpringBoot](https://spring.io/projects/spring-boot), -[MicroProfile](https://projects.eclipse.org/projects/technology.microprofile), -[Micronaut](https://micronaut.io/) or [Quarkus](https://quarkus.io/) - -### Core diff --git a/docs/spring-boot/core-starter.md b/docs/spring-boot/core-starter.md index 9fc9e148b..97b9351c8 100644 --- a/docs/spring-boot/core-starter.md +++ b/docs/spring-boot/core-starter.md @@ -252,3 +252,6 @@ public class GifFormActivity extends FormReplyActivity { } } ``` + +---- +[Home :house:](../index.md) diff --git a/docs/tech/architecture.md b/docs/tech/architecture.md new file mode 100644 index 000000000..885058944 --- /dev/null +++ b/docs/tech/architecture.md @@ -0,0 +1,46 @@ +# BDK Architecture Presentation +The Symphony BDK for Java is a multi-module library that uses [Gradle](https://gradle.org/) as build system. +This page will help to clearly understand how the library has been designed. This can be also useful for new contributors +aiming to provide additional features or implementations or existing APIs. + +## Architecture Overview +The following diagram aims to give an overview of the different layers and modules provided by the BDK library. +![Architecture Overview Diagram](architecture.svg) + +### symphony-bdk-core +The `symphony-bdk-core` is the main module that allows developers to write bots from a pure Java main application. It contains +all necessary BDK features such as: +- [configuration](../configuration.md) +- [authentication](../authentication.md) +- [datafeed](../datafeed.md) +- [services](../message.md) +- [activity API](../activity-api.md) + +#### Code Generation +The `symphony-bdk-core` module relies on the [openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md) +to generate API clients and models from official Symphony's [Swagger specifications](https://github.com/symphonyoss/symphony-api-spec). +API's clients are located under package `com.symphony.bdk.gen.api` and models under `com.symphony.bdk.gen.api.model`. + +### symphony-bdk-http +The `symphony-bdk-http-api` module defines a generic interface for performing HTTP calls. Along with this interface, it +also provides a utility `com.symphony.bdk.http.api.HttpClient` class helping developers to perform calls to external systems. +> :warning: It is important to notice that interface `com.symphony.bdk.http.api.ApiClient` is used by generated code. +> Changing contract would break the build. See [Code Generation](#code-generation). + +At the moment, two different implementations have been created for the `com.symphony.bdk.http.api.ApiClient` interface: +- `com.symphony.bdk.http.jersey2.ApiClientJersey2` contained in module `symphony-bdk-http-jersey2` (default implementation for [Core](#symphony-bdk-core)) +- `com.symphony.bdk.http.webclient.ApiClientWebClient` contained in module `symphony-bdk-http-webclient` (default implementation for [Spring Boot](#symphony-bdk-spring)) + +### symphony-bdk-template +The `symphony-bdk-template-api` module defines a set of interfaces that allows developers to load and fill text files with +data. This API is especially useful for complex MessageML templating. + +At the moment, two different module implementations have been created: +- `symphony-bdk-template-freemarker` +- `symphony-bdk-template-handlebars` + +### symphony-bdk-spring +The Symphony BDK comes also with two _starter_ modules to ease integration with the Spring Boot framework: +- `symphony-bdk-core-spring-boot-starter` that is basically a wrapper around the [symphony-bdk-core](#symphony-bdk-core) module +- `symphony-bdk-app-spring-boot-starter` that is a foundation for [Extension Applications](https://developers.symphony.com/symphony-developer/docs/overview-of-extension-applications) +backend development diff --git a/docs/tech/architecture.svg b/docs/tech/architecture.svg new file mode 100644 index 000000000..655ec7418 --- /dev/null +++ b/docs/tech/architecture.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/symphony-bdk-http/symphony-bdk-http-api/build.gradle b/symphony-bdk-http/symphony-bdk-http-api/build.gradle index 39c5d13c1..72cddda6a 100644 --- a/symphony-bdk-http/symphony-bdk-http-api/build.gradle +++ b/symphony-bdk-http/symphony-bdk-http-api/build.gradle @@ -1,10 +1,10 @@ description = 'Symphony Java BDK Core Http API' dependencies { + compileOnly 'org.projectlombok:lombok' annotationProcessor 'org.projectlombok:lombok' implementation 'org.apiguardian:apiguardian-api' - implementation 'org.glassfish.jersey.core:jersey-client' } diff --git a/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/ApiException.java b/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/ApiException.java index 91323934c..a62e282da 100644 --- a/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/ApiException.java +++ b/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/ApiException.java @@ -1,5 +1,7 @@ package com.symphony.bdk.http.api; +import com.symphony.bdk.http.api.util.TypeReference; + import lombok.Getter; import org.apiguardian.api.API; @@ -7,10 +9,8 @@ import java.util.List; import java.util.Map; -import javax.ws.rs.core.GenericType; - /** - * Main exception raised when invoking {@link ApiClient#invokeAPI(String, String, List, Object, Map, Map, Map, String, String, String[], GenericType)}. + * Main exception raised when invoking {@link ApiClient#invokeAPI(String, String, List, Object, Map, Map, Map, String, String, String[], TypeReference)}. * * Initially generated by the OpenAPI Maven Generator */ diff --git a/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/package-info.java b/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/package-info.java new file mode 100644 index 000000000..6ea592e51 --- /dev/null +++ b/symphony-bdk-http/symphony-bdk-http-api/src/main/java/com/symphony/bdk/http/api/package-info.java @@ -0,0 +1,9 @@ +/** + * This module provides contract for performing HTTP calls. + * + *

+ * WARNING: The interface {@link com.symphony.bdk.http.api.ApiClient} is used by generated code. + * Changing the contract will break code generation. + *

+ */ +package com.symphony.bdk.http.api;