Lưu trữ đối tượng Java phức tạp trong biến quy trình

1. Phép màu đằng sau việc lưu trữ đối tượng: Serialization

Khi bạn gọi runtimeService.setVariable("myVar", myObject), Camunda Engine không thể lưu trực tiếp đối tượng Java của bạn vào cơ sở dữ liệu (thường là CSDL quan hệ). Thay vào đó, nó phải thực hiện một quá trình gọi là serialization: chuyển đổi trạng thái của đối tượng thành một định dạng có thể lưu trữ hoặc truyền đi (ví dụ: một chuỗi byte hoặc một chuỗi JSON). Khi cần truy xuất lại, nó sẽ thực hiện quá trình ngược lại là deserialization.

Với kinh nghiệm lập trình của bạn, khái niệm này hẳn rất quen thuộc. Nó tương tự như cách các thư viện như Jackson hay Gson chuyển đổi một POJO (Plain Old Java Object) thành một chuỗi JSON để gửi qua API và ngược lại.

Để hiểu rõ hơn về bản chất của serialization, đặc biệt là với JSON, hãy xem video ngắn sau.

2. Các định dạng Serialization trong Camunda

Camunda hỗ trợ nhiều định dạng serialization, nhưng có hai loại chính bạn cần quan tâm.

Sau khi đọc tài liệu, chúng ta có thể tóm tắt như sau:

Khuyến nghị: Gần như trong mọi trường hợp, đặc biệt là các kiến trúc hướng microservice, bạn nên ưu tiên sử dụng JSON làm định dạng serialization cho các đối tượng phức tạp.

3. Thực hành: Làm việc với đối tượng phức tạp

Giờ chúng ta sẽ áp dụng kiến thức này vào quy trình xử lý đơn hàng. Thay vì truyền các biến riêng lẻ như orderId, customerName, amount, chúng ta sẽ tạo một đối tượng duy nhất là OrderDetails.

Bước 1: Tạo lớp OrderDetails

Trong project Spring Boot của bạn, tạo một lớp POJO mới tên là OrderDetails.java.

package com.example.camunda.process.solution;

import java.io.Serializable;
import java.util.List;

// implement Serializable là cần thiết để Camunda có thể xử lý đối tượng này
public class OrderDetails implements Serializable {

    private static final long serialVersionUID = 1L;

    private String orderId;
    private String customerName;
    private List<String> items;
    private Double totalAmount;

    // Constructors, Getters and Setters
    public OrderDetails() {}

    public OrderDetails(String orderId, String customerName, List<String> items, Double totalAmount) {
        this.orderId = orderId;
        this.customerName = customerName;
        this.items = items;
        this.totalAmount = totalAmount;
    }

    public String getOrderId() { return orderId; }
    public void setOrderId(String orderId) { this.orderId = orderId; }
    public String getCustomerName() { return customerName; }
    public void setCustomerName(String customerName) { this.customerName = customerName; }
    public List<String> getItems() { return items; }
    public void setItems(List<String> items) { this.items = items; }
    public Double getTotalAmount() { return totalAmount; }
    public void setTotalAmount(Double totalAmount) { this.totalAmount = totalAmount; }

    @Override
    public String toString() {
        return "OrderDetails{" +
                "orderId='" + orderId + '\'' +
                ", customerName='" + customerName + '\'' +
                ", items=" + items +
                ", totalAmount=" + totalAmount +
                '}';
    }
}

Lưu ý: Mặc dù chúng ta sẽ ưu tiên JSON, việc implements Serializable vẫn là một good practice vì engine có thể cần đến nó trong một số trường hợp, và nó cũng là một cách đánh dấu rõ ràng rằng đối tượng này được thiết kế để có thể được truyền đi.

Bước 2: Bắt đầu quy trình với biến đối tượng

Có nhiều cách để khởi tạo quy trình với biến đối tượng. Một cách rất phổ biến trong môi trường microservice là qua REST API. Bạn có thể chỉ định rõ rằng biến của bạn là một đối tượng JSON.

Đây là một ví dụ về payload của lời gọi POST /process-definition/key/{key}/start để khởi tạo quy trình của chúng ta. Bạn có thể dùng Postman hoặc một REST client khác để thử.

{
  "variables": {
    "orderDetails": {
      "value": "{\"orderId\":\"A123\",\"customerName\":\"Trong Nguyen\",\"items\":[\"Laptop\",\"Mouse\"],\"totalAmount\":25500000.0}",
      "type": "Object",
      "valueInfo": {
        "objectTypeName": "com.example.camunda.process.solution.OrderDetails",
        "serializationDataFormat": "application/json"
      }
    }
  }
}

objectTypeName cho Camunda biết lớp Java tương ứng khi cần deserialize. serializationDataFormat yêu cầu engine sử dụng SPIN để xử lý biến này dưới dạng JSON.

Một ví dụ thực tế khác cho thấy cách lưu một danh sách lỗi dưới dạng JSON từ một script task.

Bước 3: Truy xuất thuộc tính đối tượng trong quy trình

Một trong những ưu điểm lớn nhất của việc lưu đối tượng là bạn có thể truy cập các thuộc tính của nó một cách dễ dàng bằng Expression Language (EL) ở bất kỳ đâu trong quy trình.

Mở file BPMN của bạn trong Camunda Modeler.

1. Tại User Task "Duyệt đơn hàng": Bạn có thể thay đổi tên (Name) của task để hiển thị thông tin chi tiết hơn.
   • Name: Duyệt đơn hàng cho KH: ${orderDetails.customerName}
   • Camunda sẽ tự động gọi getOrderDetails().getCustomerName() khi hiển thị tên task.
2. Tại Exclusive Gateway "Đơn hàng > 5M?": Bạn có thể thay đổi điều kiện để đọc trực tiếp từ thuộc tính của đối tượng.
   • Chọn mũi tên "Có", trong tab "Condition", đặt Condition Expression là: ${orderDetails.totalAmount > 5000000}.

Bước 4: Truy xuất đối tượng trong Java Delegate

Bây giờ, hãy cập nhật ProcessResultDelegate để làm việc với đối tượng OrderDetails thay vì các biến riêng lẻ.

@Override
public void execute(DelegateExecution execution) throws Exception {
    // Lấy toàn bộ đối tượng OrderDetails
    // Camunda sẽ tự động deserialize chuỗi JSON trở lại thành object
    OrderDetails details = (OrderDetails) execution.getVariable("orderDetails");

    // Nếu bạn muốn lấy dưới dạng SPIN object để thao tác với JSON
    // SpinJsonNode jsonDetails = (SpinJsonNode) execution.getVariableTyped("orderDetails").getValue();

    boolean approved = (Boolean) execution.getVariable("approved");

    System.out.println("--- Xử lý kết quả cho đơn hàng ---");
    if (details != null) {
        System.out.println("Thông tin đơn hàng: " + details.toString());
    }
    System.out.println("Trạng thái duyệt: " + (approved ? "Đã duyệt" : "Bị từ chối"));
    System.out.println("---------------------------------");
}

Deploy và kiểm tra:

1. Deploy lại ứng dụng Spring Boot.
2. Sử dụng Postman để bắt đầu một process instance mới với payload JSON như ở Bước 2.
3. Vào Camunda Tasklist, bạn sẽ thấy tên của User Task đã hiển thị tên khách hàng.
4. Hoàn thành task (nhớ đặt biến approved).
5. Kiểm tra console log, bạn sẽ thấy ProcessResultDelegate in ra toàn bộ thông tin của đối tượng OrderDetails.
6. Trong Cockpit, xem process instance vừa chạy. Ở tab Variables, bạn sẽ thấy biến orderDetails. Nhấn vào biểu tượng {} bên cạnh, bạn có thể xem nội dung JSON đã được serialize, cực kỳ hữu ích cho việc debug.

4. Tổng kết

Qua bài học này, bạn đã trang bị cho mình một công cụ cực kỳ mạnh mẽ để xử lý dữ liệu trong Camunda.

Những điểm chính cần nhớ:

• Camunda lưu trữ các đối tượng phức tạp bằng cách serialization.
• JSON là định dạng serialization được khuyến nghị vì tính linh hoạt, dễ đọc và khả năng tương tác cao (đặc biệt quan trọng cho microservices).
• Sử dụng Camunda SPIN để làm việc với các biến JSON/XML.
• Khi một đối tượng được lưu trong biến quy trình, bạn có thể dễ dàng truy cập các thuộc tính của nó bằng Expression Language (ví dụ: ${myObject.myProperty}).
• Khi lấy biến trong code Java, Camunda sẽ tự động deserialize về lại POJO nếu có class tương ứng trong classpath.

Xem trước bài học tiếp theo

Chúng ta đã dành cả Module 4 để tìm hiểu sâu về cách quản lý dữ liệu và biến trong quy trình. Bây giờ bạn đã có nền tảng vững chắc về dữ liệu, đã đến lúc chúng ta khám phá các cấu trúc điều khiển luồng phức tạp hơn.

Trong bài học đầu tiên của Module 5, chúng ta sẽ đi sâu vào Exclusive Gateway (XOR), tìm hiểu cách implement các điều kiện rẽ nhánh phức tạp hơn bằng cách sử dụng các biến quy trình mà bạn vừa học cách quản lý.