README.adoc

= Bonita Java Client
//:doctype: book
:sectnums:
//:source-highlighter: highlightjs
:idprefix:
:idseparator: -
:sectlinks:
:sectanchors:
//:linkcss: false
:allow-uri-read:
:imagesdir: ./doc/images

:icon-party: 🥳

ifndef::env-github[:icons: font]
ifdef::env-github[]
:status:
:outfilesuffix: .adoc
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Vars
:project-group-id: org.bonitasoft.web
:project-artifact-id: bonita-java-client
:project-version: 2.0.0-SNAPSHOT
:bonita-short-version: 7.15
:orga: bonitasoft
:uri-org: https://github.com/{orga}
:uri-repo: {uri-org}/{project-artifact-id}
:uri-issues: {uri-repo}/issues
:uri-contributors: {uri-repo}/graphs/contributor
:uri-rel-file-base: link:
:uri-rel-tree-base: link:
ifdef::env-site,env-yard[]
:uri-rel-file-base: {uri-repo}/blob/master/
:uri-rel-tree-base: {uri-repo}/tree/master/
endif::[]
:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
:uri-license: {uri-rel-file-base}LICENSE.md

image::Bonitasoft_Community_RGB.png[Bonitasoft,link="https://www.bonitasoft.com",width=450px]

ifdef::status[]
image:{uri-repo}/workflows/workflow-build/badge.svg[Build,link="{uri-repo}/actions?query=workflow%3Aworkflow-build"]
image:https://img.shields.io/github/v/release/{orga}/{project-artifact-id}?color=blue&label=Release[Release,link="{uri-repo}/releases"]
image:https://img.shields.io/maven-central/v/{project-group-id}/{project-artifact-id}.svg?label=Maven%20Central&color=orange[Maven Central,link="https://search.maven.org/search?q=g:%22{project-group-id}%22%20AND%20a:%22{project-artifact-id}%22"]
image:https://sonarcloud.io/api/project_badges/measure?project=bonitasoft_bonita-java-client&metric=alert_status[Sonar,link=https://sonarcloud.io/dashboard?id=bonitasoft_bonita-java-client]
image:https://img.shields.io/badge/License-GPL%20v2-yellow.svg[License,link="{uri-license}"]
endif::[]

This project is the official web client for Bonita when working with Java (or on the JVM).

It is based on an https://swagger.io/specification/[OpenAPI image:openapi.png[OpenAPI,width=30px]^] specification for **Bonita {bonita-short-version}** `Enterprise` edition.
This means that this client includes all `Community` operations plus some that are only supported by `Enterprise` editions servers.

'''

== Features

* Cover publicly available http endpoints of Bonita Platform {bonita-short-version} and onwards
* Built-in Bonita authentication support (SSO not supported yet)
* Higher level code than raw openapi client to ease developer journey

== Getting started

The client library available from https://search.maven.org/search?q={project-group-id}%20AND%20a:{project-artifact-id}[Maven Central], you can use it in your Maven project by adding the following to your *pom.xml*:

[source,xml,subs="attributes+"]
----
<dependency>
    <groupId>{project-group-id}</groupId>
    <artifactId>{project-artifact-id}</artifactId>
    <version>{project-version}</version>
</dependency>
----

NOTE: Snapshots versions are available at https://oss.sonatype.org/content/repositories/snapshots/

The following code creates a java client instance targeting a bonita server listening at `http://localhost:8080/bonita`. After login in, it queries the deployed processes
with pagination parameters (page index: 0,page size: 20)

[source,java,subs="attributes"]
----
// Create a client
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita").build();

// Login
Session session = client.login("username","password");
// Log Bonita server version
log.debug("Bonita version: {}", session.getVersion());

// Use the client &#x1F973;
List<BusinessProcess> businessProcesses = client.processes().searchProcesses(0, 20);

// Logout when done
client.logout();
----

== Configuration

=== Logging

This client can log HTTP requests made to Bonita Platform.

Different log level are available. Default level is `OFF`

- `FULL`: Headers + Body
- `HEADER`: Headers
- `BASIC`: HTTP trace (url + verb + response code)
- `OFF`: No log

[source, java]
----
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .logContentLevel(LogContentLevel.BASIC)
    .build();
----

The logger name is `org.bonitasoft.web.client.BonitaClient` and logging is done with to slf4j so if you're using logback implementation, you may configure your logger like this :

[source, xml]
----
<logger name="org.bonitasoft.web.client.BonitaClient" level="INFO"/>
----


=== http timeouts

The following code show how you can customize the client http timeouts.

[source, java]
----
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .connectTimeoutInSeconds(int connectTimeoutInSeconds)
        .readTimeoutInSeconds(int readTimeoutInSeconds)
        .writeTimeoutInSeconds(int writeTimeoutInSeconds)
    .build();
----

=== SSL

If you need for any reason to disable ssl certificate check, here is the code to do it:

[source, java]
----
BonitaClient client = BonitaClient.builder("https://me.bonitacloud.com/")
        // Disable certificate check
        .disableCertificateCheck(true)
    .build();
----

WARNING: Please note that this is not recommended from a security point of view !

=== Custom Jackson object mapper

[source, java]
----
// Create your custom ObjectMapper
ObjectMapper myObjectMapper = new ObjectMapper();

// Configure bonita client to use your custom ObjectMapper
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .objectMapper(myObjectMapper)
    .build();
----


=== Custom OkHttp Client

[source, java]
----
// Create your custom OkHttp client
OkHttpClient myOkHttpClient = new OkHttpClient.Builder().build();

// Configure bonita client to use your custom OkHttp client
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        okHttpClient(myOkHttpClient)
    .build();
----

=== Custom Feign configuration

The current implementation of the client use OpenFeign internally. If you need to fine tune the feign aspect, it is possible but remember this may change in future version.

[source, java]
----
// Create your custom feign builder
Feign.Builder myFeignBuilder = new Feign.Builder();

BonitaClientBuilder builder = BonitaClient.builder("http://localhost:8080/bonita");
// Cast builder to BonitaFeignClientBuilder class
BonitaFeignClientBuilder bonitaClientBuilder = (BonitaFeignClientBuilder) builder;
BonitaClient client = bonitaClientBuilder
        // Configure bonita client to use your custom feign builder
        .feignBuilder(myFeignBuilder)
    .build();
----

== Samples

=== BDM typed queries

Bonita allow users to define their own custom "named" queries. That's why this client can't have java object ready to be mapped to the query results. But the client allow
developers to specify the desired returned type when performing custom queries.

As an example, let's say with have a model in our client project code for `Post`,`Comment` and `Author` defined this way

[source, java]
----
public interface Post {
    Author getAuthor();
    String getTitle();
    String getContent();
    List<Comment> getComments();
}

public interface Comment {
    Long getUserId();
    LocalDateTime getCreationDate();
	String getContent();
}

public class Author {
    private String firstName;
    private String lastName;
    // Getter and Setter omitted ...
}
----

Interface with `Getter` methods are a good choice since we consider the retrieved data as immutable.

Bonus, it allow for lazy fetch of relations as defined in the BDM !

[source, java]
----
// Count comment and map response to an Integer
Integer count = bonitaClient.bdm().querySingle("com.company.model.Comment", "countForFind", Integer.class);

// List comments and map response to a list of Comment
List<Post> posts = bonitaClient.bdm().query("com.company.model.Post", "find", Post.class);

Post post = posts.get(O);
// This will trigger an HTTP GET request to get the related comments from the BDM
List<Comment> comments = post.getComments();
----

If you prefer a map style like approach, you can still use the BusinessData class.
[source, java]
----
List<BusinessData> comments = bonitaClient.bdm().query("com.company.model.Comment", "find", BusinessData.class);
String content = comments.get(0).get("content")
----

== Developing

=== Prerequisite

- a git client
- a java (jdk8 or higher)
- maven (optional if you chose to use https://github.com/takari/maven-wrapper[maven wrapper script])
- Docker for integration tests

=== Building

This is a standard maven project. To install the java client library to your local Maven repository, simply execute:

[source,bash,subs="attributes"]
----
git clone {uri-repo}.git
cd {project-artifact-id}/
mvn install
----

The build should produce under the `target/` folder (and in your local maven repository) a jar archive named `bonita-java-client-1.0.0-SNAPSHOT.jar`

For more details about apache maven, please refer to the https://maven.apache.org/guides/getting-started/[documentation]

=== Format source code

This project uses Spotless to ensure a consistent formatting.
To apply the configured formatting rules use the following Maven command: 

[source, bash]
----
./mvnw spotless:apply
----

=== Update OpenAPI spec version

The OpenAPI spec is retrieve from the [bonita-openapi](https://github.com/bonitasoft/bonita-openapi/) repository releases. To  update the spec version you must:

* Update the `bonita-openapi.version` property in the `pom.xml`
* Run the following Maven command:

[source, bash]
----
./mvnw groovy:execute@update-spec
----

You can then regenerate the feign stubs.

=== Regenerate feign stubs

If the openapi specification changed, you can regenerates the feign stubs with the following command.

WARNING: Be careful, some client stubs are marked as ignored in `.openapi-generator-ignore` file, since they were customized (like returning a `feign.Response` instead of a model object)

[source,bash,subs="attributes"]
----
mvn generate-sources -Dcodegen.skip=false
----

=== Branches

The adopted worlfow is for now the Gitflow one.

Please refers to this article for more info: https://jeffkreeftmeijer.com/git-flow/

== Release

- Create a branch for the desired version. ex: `release/1.0.0`. You can use the `set-version.sh` script to align declared versions in sources (pom.xml,readme.adoc,...)
- Push branch, make a pull request to `master` and review release with others
- Once you are happy with the content of the release branch, merge pull request to master branch using `Merge pull request` button (&#9888; Do not squash or rebase)
- Wait the build to succeed
- Go to https://oss.sonatype.org/ to close and release the staging repository and now you're done ! {icon-party}


NOTE: Do not update your local `dev` branch after a release has been done ! The release job will perform the dev branch update itself !

== Getting Help

The *{orga}* organization on GitHub hosts the project's source code, issue trackers, and other projects.

Source repository (git):: {uri-repo}
Issue tracker:: {uri-issues}
Organization on GitHub:: {uri-org}

== Copyright and License

Use of this software is granted under the terms of the GNU GENERAL PUBLIC LICENSE.

See the {uri-license}[LICENSE] for the full license text.

ifndef::env-site[]
== Changelog

ifeval::[{safe-mode-level} < 20]
include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
endif::[]

Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
endif::[]

== Links

- Project homepage: https://github.com/bonitasoft/{project-artifact-id}/
- Repository: https://github.com/bonitasoft/{project-artifact-id}/
- Issue tracker: https://github.com/bonitasoft/{project-artifact-id}/issues. +
  In case of sensitive bugs like security vulnerabilities, please contact rd@bonitasoft.com directly instead of using issue tracker. We value your effort to improve the security and privacy of this project!
- Current Bonita REST API documentation: https://documentation.bonitasoft.com/bonita/{bonita-short-version}/rest-api-overview
- OpenAPI specification: https://swagger.io/specification/
- OpenAPI generator: https://github.com/OpenAPITools/openapi-generator
- OpenFeign: https://github.com/OpenFeign/feign
- slf4j: http://www.slf4j.org/
- Jackson ObjectMapper: https://github.com/FasterXML/jackson-databind