Merge branch 'release/1.0.0'

README.adoc

@@ -1,4 +1,4 @@
-[cols="a,a,a,a,a,a"]
+[cols="a,a,a,a,a,a,a"]
 |===
 | // ci
 image::https://github.com/holunda-io/camunda-bpm-data/workflows/default/badge.svg[caption="Build Status", link=https://github.com/holunda-io/camunda-bpm-data/actions]
@@ -12,22 +12,209 @@ image::https://api.codacy.com/project/badge/Grade/653136bd5cad48c8a9f2621ee304ff
 image::https://img.shields.io/badge/License-Apache%202.0-blue.svg[caption="License", link="https://www.holunda.io/camunda-bpm-data/license"]
 | // changelog
 image::https://img.shields.io/badge/CHANGES----blue.svg[caption="Change log" link="https://www.holunda.io/camunda-bpm-data/changelog"]
+| // gitter
+image::https://badges.gitter.im/holunda-io/camunda-bpm-data.svg[caption="Gitter", link="https://gitter.im/holunda-io/camunda-bpm-data?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge"]
 |===
 
+== Camunda BPM Data
 
-== Quick Start
+> Beautiful process data handling for Camunda BPM.
 
-If you just want to start using the library, please consult our link:https://www.holunda.io/camunda-bpm-data/quick-start[Quick Start]
-guide.
+== Why to use this library in every Camunda project?
 
-== User Guide
+If you are a software engineer and run process automation projects in your company or on behalf of the customer
+based on Camunda Process Engine, you probably are familiar with process variables. Camunda offers an API to access
+them and thereby manipulate the state of the process execution - one of the core features during process automation.
 
-If you have any questions regarding configuration of Camunda BPM Data please
-have a look to our primary documentation - the link:https://www.holunda.io/camunda-bpm-data/wiki/user-guide[User Guide].
+Unfortunately, as a user of the Camunda API, you have to exactly know the variable type (so the Java class behind it).
+For example, if you store a String in a variable `"orderId"` you must extract it as a String in every piece of code.
+Since there is no code connection between the different code parts, but the BPMN process model orchestrates
+these snippets to a single process execution, it makes refactoring and testing of process automation projects
+error-prone and challenging.
+
+This library helps you to overcome these difficulties and make access, manipulation and testing process variables really
+easy and convenient. We leverage the Camunda API and offer you not only a better API but also some link:https://www.holunda.io/camunda-bpm-data/wiki/user-guide/features[additional features].
+
+If you want to read more about data in Camunda processes, have a look on those articles:
+
+- https://medium.com/holisticon-consultants/data-in-process-part-1-2620bf9abd76[Data in Process (Part 1)]
+- https://medium.com/holisticon-consultants/data-in-process-part-2-7c6a109e6ee2[Data in Process (Part 2)]
+
+
+== Quick Introduction
+
+=== Setup
+If you just want to start using the library, put the following dependency into your project `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+  <groupId>io.holunda.data</groupId>
+  <artifactId>camunda-bpm-data</artifactId>
+  <version>1.0.0</version>
+</dependency>
+----
+
+If you are using Gradle Kotlin DSL add to your `build.gradle`:
+[source,kotlin]
+----
+implementation("io.holunda.data:camunda-bpm-data:1.0.0")
+----
+
+For Gradle Groovy DSL add to your `build.gradle`:
+[source,groovy]
+----
+implementation 'io.holunda.data:camunda-bpm-data:1.0.0'
+----
+
+=== Variable declaration
+Now your setup is completed and you can declare your variables like this:
+
+[source,java]
+----
+
+import io.holunda.camunda.bpm.data.factory.VariableFactory;
+import static io.holunda.camunda.bpm.data.CamundaBpmData.*;
+
+public class OrderApproval {
+  public static final VariableFactory<String> ORDER_ID = stringVariable("orderId");
+  public static final VariableFactory<Order> ORDER = customVariable("order", Order.class);
+  public static final VariableFactory<Boolean> ORDER_APPROVED = booleanVariable("orderApproved");
+  public static final VariableFactory<BigDecimal> ORDER_TOTAL = customVariable("orderTotal", BigDecimal.class);
+  public static final VariableFactory<OrderPosition> ORDER_POSITION = customVariable("orderPosition", OrderPosition.class);
+}
+----
+
+=== Variable access from Java Delegate
+And finally, you want to access them from your Java delegates, Execution or Task Listeners or simple Java components:
+
+[source,java]
+----
+public class MyDelegate implements JavaDelegate {
+  @Override
+  public void execute(DelegateExecution execution) {
+    VariableReader reader = CamundaBpmData.reader(execution);
+    OrderPosition orderPosition = reader.get(ORDER_POSITION);
+    BigDecimal oldTotal = reader.getOptional(ORDER_TOTAL).orElse(BigDecimal.ZERO);
+
+    BigDecimal newTotal = oldTotal.add(calculatePrice(orderPosition));
+    ORDER_TOTAL.on(execution).setLocal(newTotal);
+  }
+
+  private BigDecimal calculatePrice(OrderPosition orderPosition) {
+     return orderPosition.getNetCost().multiply(BigDecimal.valueOf(orderPosition.getAmount()));
+  }
+}
+----
+
+=== Variable access from REST Controller
+
+Now imagine you are implementing a REST controller for a user task form which
+loads data from the process application, displays it, captures some input and
+sends that back to the process application to complete the user task. By doing so,
+you will usually need to access process variables. Here is an example:
+
+[source, java]
+----
+@RestController
+@RequestMapping("/task/approve-order")
+public class ApproveOrderTaskController {
+
+    private final TaskService taskService;
+
+    public ApproveOrderTaskController(TaskService taskService) {
+        this.taskService = taskService;
+    }
+
+    @GetMapping("/{taskId}")
+    public ResponseEntity<ApproveTaskDto> loadTask(@PathVariable("taskId") String taskId) {
+        Order order = ORDER.from(taskService, taskId).get();
+        return ResponseEntity.ok(new ApproveTaskDto(order));
+    }
+
+    @PostMapping("/{taskId}")
+    public ResponseEntity<Void> completeTask(@PathVariable("taskId") String taskId, @RequestBody ApproveTaskCompleteDto userInput) {
+        VariableMap vars = builder()
+            .set(ORDER_APPROVED, userInput.getApproved())
+            .build();
+        taskService.complete(taskId, vars);
+        return ResponseEntity.noContent().build();
+    }
+}
+
+----
+
+=== Testing correct variable access
+
+If you want to write the test for the REST controller, you will need to stub
+the task service and verify that the correct variables has been set. To simplify
+these tests, we created an additional library module `camunda-bpm-data-test`.
+Please put the following dependency into your `pom.xml`:
+[source,xml]
+----
+<dependency>
+  <groupId>io.holunda.data</groupId>
+  <artifactId>camunda-bpm-data-test</artifactId>
+  <version>1.0.0</version>
+  <scope>test</scope>
+</dependency>
+----
+
+Now you can use `TaskServiceVariableMockBuilder` to stub correct behavior of Camunda Task Service
+and `TaskServiceVerifier` to verify the correct access to variables easily. Here is the JUnit
+test of the REST controller above, making use of `camunda-bpm-data-test`.
+
+[source,java]
+----
+public class ApproveOrderTaskControllerTest {
+
+    private static Order order = new Order("ORDER-ID-1", new Date(), new ArrayList<>());
+    private TaskService taskService = mock(TaskService.class);
+    private TaskServiceMockVerifier verifier = taskServiceMockVerifier(taskService);
+    private ApproveOrderTaskController controller = new ApproveOrderTaskController(taskService);
+    private String taskId;
+
+    @Before
+    public void prepareTest() {
+        reset(taskService);
+        taskId = UUID.randomUUID().toString();
+    }
+
+    @Test
+    public void testLoadTask() {
+        // given
+        taskServiceVariableMockBuilder(taskService).initial(ORDER, order).build();
+        // when
+        ResponseEntity<ApproveTaskDto> responseEntity = controller.loadTask(taskId);
+        // then
+        assertThat(responseEntity.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(responseEntity.getBody()).isEqualTo(new ApproveTaskDto(order));
+        verifier.verifyGet(ORDER, taskId);
+        verifier.verifyNoMoreInteractions();
+    }
+
+    @Test
+    public void testCompleteTask() {
+        // when
+        ApproveTaskCompleteDto response = new ApproveTaskCompleteDto(true);
+        ResponseEntity<Void> responseEntity = controller.completeTask(taskId, response);
+        // then
+        assertThat(responseEntity.getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
+        verifier.verifyComplete(builder().set(ORDER_APPROVED, response.getApproved()).build(), taskId);
+        verifier.verifyNoMoreInteractions();
+    }
+}
+----
+
+=== Further documentation
+
+For further details, please consult our link:https://www.holunda.io/camunda-bpm-data/quick-start[Quick Start]
+guide or have a look to our primary documentation - link:https://www.holunda.io/camunda-bpm-data/wiki/user-guide[the User Guide].
 
 == Working Example
 
-See our link:https://www.holunda.io/camunda-bpm-data/wiki/user-guide/examples[Examples] for usage and configuration.
+We prepared some typical usage scenarios and implemented two example projects in Java and Kotlin.
+See our link:https://www.holunda.io/camunda-bpm-data/wiki/user-guide/examples[Examples] section for usage and configuration.
 
 == License
 

docs/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.holunda.data</groupId>
     <artifactId>camunda-bpm-data-parent</artifactId>
-    <version>0.0.6</version>
+    <version>1.0.0</version>
   </parent>
 
   <artifactId>camunda-bpm-data-docs</artifactId>

docs/src/orchid/resources/changelog/1.0/1.0.0.ad

@@ -0,0 +1,24 @@
+---
+version: 1.0.0
+---
+
+== News
+
+* Run through a internal review in Holisticon BPM expert team
+
+== Breaking changes
+
+* The `CamundaBpmData.builder(xxx)` methods and implementing classes where renamed to `XxxWriter` since where didn't follow the Builder pattern. #49
+* The `camunda-bpm-data-kotlin` module is removed and its content is now a part of the `camunda-bpm-data` JAR
+* The `camunda-bpm-data-mockito` module is renamed into `camunda-bpm-data-test` and will contain helpers for testing.
+
+== Features
+* Better documentation and catchy README
+* Implementation of Anti-Corruption-Layer #47
+* VariableReader convenience methods to access multiple variables have been implemented, see #46
+* Provided type collection detector for SPIN/Jackson (currently as PR for SPIN and example code)
+
+== Bugfixes
+
+* Evaluation of complex guards fail if exists condition isn't fulfilled.
+* NPE passing null to set, see #46

docs/src/orchid/resources/homepage.md

@@ -4,12 +4,23 @@ layout: frontPage
 
 ## Why should I use this?
 
-This library provides convenient tooling for access to process variables in Camunda BPM engine. 
+If you are a software engineer and run process automation projects in your company or on behalf of the customer
+based on Camunda Process Engine, you probably are familiar with process variables. Camunda offers an API to access
+them and thereby manipulate the state of the process execution - one of the core features during process automation.
+
+Unfortunately, as a user of the Camunda API, you have to exactly know the variable type (so the Java class behind it).
+For example, if you store a String in a variable `"orderId"` you must extract it as a String in every piece of code.
+Since there is no code connection between the different code parts, but the BPMN process model orchestrates
+these snippets to a single process execution, it makes refactoring and testing of process automation projects
+error-prone and challenging.
+
+This library helps you to overcome these difficulties and make access, manipulation and testing process variables really
+easy and convenient. We leverage the Camunda API and offer you not only a better API but also some [additional features](https://www.holunda.io/camunda-bpm-data/wiki/user-guide/features).
 
 ## How to start?
 
 A good starting point is the [Quick Start](./quick-start). For more detailed documentation, please have a look at
-[User Guide](./wiki/user-guide).
+[User Guide](./wiki/user-guide). 
 
 ## Get in touch