fix: reserve stock before charging and validate order quantity

The order flow is now reserve, charge, release on failure. Inventory rejects non-positive quantities and its errors are surfaced, the access policy runs before the registry lookup, the statelessness and interoperability wording is corrected, and confirmations carry the customer id. The class diagram is a rendered PNG.

Author: ylcn91

service-oriented-architecture/README.md

@@ -49,7 +49,9 @@ flowchart LR
     Order -.->|orchestrates via bus| Bus
 ```
 
-Because every service is stateless between calls, each one can be scaled independently. In the example the in-memory maps stand in for each service's own datastore, and the bus stands in for the network protocol (SOAP, REST or messaging) that would carry the messages in a deployed system.
+Because no service keeps per-conversation session state, each one can be scaled independently; the state a service does own is shared between all its callers and guarded for concurrent access. In the example the in-memory maps stand in for each service's own datastore, and the bus stands in for the network protocol (SOAP, REST or messaging) that would carry the messages in a deployed system.
+
+![Service-Oriented Architecture class diagram](./etc/service-oriented-architecture.urm.png)
 
 ## Programmatic Example of Service-Oriented Architecture Pattern in Java
 
@@ -64,7 +66,7 @@ public interface Service {
 }
 ```
 
-Messages are coarse-grained and self-describing. The payload is plain data, which is what makes the contract interoperable: the same request could travel as SOAP, JSON or any other wire format.
+Messages are coarse-grained and self-describing. The request payload is plain data, which is what makes the contract interoperable: the same request could travel as SOAP, JSON or any other wire format. Responses in this demo carry typed Java objects for brevity; a deployed system would describe them as plain data too.
 
 ```java
 public record ServiceRequest(
@@ -102,7 +104,7 @@ public class ServiceRegistry {
 }
 ```
 
-The bus is the communication backbone. It resolves the target through the registry, applies cross-cutting concerns in a single place (access control, tracing, timing) and turns provider failures into error responses so that consumers never see provider exceptions.
+The bus is the communication backbone. It applies cross-cutting concerns in a single place (access control, tracing, timing), resolves the target through the registry and turns provider failures into error responses so that consumers never see provider exceptions. The access check runs before the lookup, so a caller that may not reach a service learns nothing about what the registry holds.
 
 ```java
 @Slf4j
@@ -113,15 +115,15 @@ public class ServiceBus {
   public ServiceBus(ServiceRegistry registry, AccessPolicy policy) { ... }
 
   public ServiceResponse send(ServiceRequest request) {
-    var service = registry.lookup(request.service());
-    if (service.isEmpty()) {
-      return ServiceResponse.error("No such service: " + request.service());
-    }
     if (!policy.allows(request)) {
       LOGGER.warn("Access denied to {}.{} for {} caller", request.service(), request.operation(),
           request.credential() == null ? "anonymous" : "credentialed");
       return ServiceResponse.error("Access denied to " + request.service());
     }
+    var service = registry.lookup(request.service());
+    if (service.isEmpty()) {
+      return ServiceResponse.error("No such service: " + request.service());
+    }
     LOGGER.info("-> {}.{} payload={}", request.service(), request.operation(), request.payload());
     var start = System.nanoTime();
     try {
@@ -160,7 +162,7 @@ var denied = bus.send(new ServiceRequest("payment", "charge",
 // denied = ServiceResponse[success=false, body=null, message=Access denied to payment]
 ```
 
-Each enterprise service owns exactly one business capability and is stateless between calls. Operations are dispatched with a switch expression on the operation name.
+Each enterprise service owns exactly one business capability and keeps no per-conversation session state; the state it does own is private to it and guarded for concurrent access. Operations are dispatched with a switch expression on the operation name.
 
 ```java
 public class CustomerService implements Service {
@@ -177,10 +179,12 @@ public class CustomerService implements Service {
 }
 ```
 
-`InventoryService` answers `checkStock` and `reserve`, and `PaymentService` answers `charge` in the same style.
+`InventoryService` answers `checkStock`, `reserve` and `release`, and `PaymentService` answers `charge` in the same style. Both reject a non-positive quantity or amount, because a service validates its own input rather than trusting its callers.
 
 The composite `OrderService` is where SOA shows its strength. It implements the same contract as the others, but delivers a higher level capability by orchestrating the lower level services through the bus. It depends only on service names and message contracts, never on the provider classes, and it forwards the caller's credential so the bus can authorise every downstream call.
 
+No transaction spans the services, so the order service compensates instead: it reserves the stock before it charges the customer, and releases the reservation again when the charge fails. Doing it the other way round would leave a customer charged for an order that was never reserved.
+
 ```java
 @RequiredArgsConstructor
 public class OrderService implements Service {
@@ -199,22 +203,30 @@ public class OrderService implements Service {
     }
     var stock = bus.send(new ServiceRequest(INVENTORY_SERVICE, "checkStock",
         Map.of("sku", sku, "quantity", quantity), credential));
-    if (!stock.success() || !Boolean.TRUE.equals(stock.body())) {
+    if (!stock.success()) {
+      return ServiceResponse.error("Order rejected: " + stock.message());
+    }
+    if (!Boolean.TRUE.equals(stock.body())) {
       return ServiceResponse.error("Order rejected: insufficient stock for " + sku);
     }
+    var reservation = bus.send(new ServiceRequest(INVENTORY_SERVICE, "reserve",
+        Map.of("sku", sku, "quantity", quantity), credential));
+    if (!reservation.success()) {
+      return ServiceResponse.error("Order rejected: " + reservation.message());
+    }
     var payment = bus.send(new ServiceRequest(PAYMENT_SERVICE, "charge",
         Map.of("customerId", customerId, "amount", amount), credential));
     if (!payment.success()) {
+      bus.send(new ServiceRequest(INVENTORY_SERVICE, "release", // compensate the reservation
+          Map.of("sku", sku, "quantity", quantity), credential));
       return ServiceResponse.error("Order rejected: " + payment.message());
     }
-    bus.send(new ServiceRequest(INVENTORY_SERVICE, "reserve",
-        Map.of("sku", sku, "quantity", quantity), credential));
     return ServiceResponse.ok(new OrderConfirmation(...));
   }
 }
 ```
 
-The application wires everything together behind a bus that protects the payment service and sends four requests: an order with a valid credential that succeeds, an order that fails because of stock, a request for a service nobody registered, and an anonymous order that the bus stops at the payment step.
+The application wires everything together behind a bus that protects the payment service and sends four requests: an order with a valid credential that succeeds, an order that fails because of stock, a request for a service nobody registered, and an anonymous order that the bus stops at the payment step, after which the order service releases the stock it had already reserved.
 
 ```java
 var registry = new ServiceRegistry();
@@ -239,36 +251,50 @@ var denied = bus.send(new ServiceRequest(OrderService.NAME, "placeOrder",
 Running the program produces output similar to this:
 
 ```
+Bootstrapping the service registry and the service bus
 Registered service 'customer' (CustomerService)
 Registered service 'inventory' (InventoryService)
 Registered service 'payment' (PaymentService)
 Registered service 'order' (OrderService)
--> order.placeOrder payload={amount=899.0, quantity=2, sku=LAPTOP, customerId=C-1}
+Available services: [customer, order, inventory, payment]
+Placing an order with a valid credential, it should succeed
+-> order.placeOrder payload={amount=899.0, customerId=C-1, quantity=2, sku=LAPTOP}
 -> customer.getCustomer payload={customerId=C-1}
 <- customer.getCustomer success=true in 0 ms
--> inventory.checkStock payload={quantity=2, sku=LAPTOP}
+-> inventory.checkStock payload={sku=LAPTOP, quantity=2}
 <- inventory.checkStock success=true in 0 ms
+-> inventory.reserve payload={sku=LAPTOP, quantity=2}
+<- inventory.reserve success=true in 0 ms
 -> payment.charge payload={amount=899.0, customerId=C-1}
 <- payment.charge success=true in 0 ms
--> inventory.reserve payload={quantity=2, sku=LAPTOP}
-<- inventory.reserve success=true in 0 ms
 <- order.placeOrder success=true in 1 ms
-Order outcome: ServiceResponse[success=true, body=OrderConfirmation[orderId=ORD-1, customerName=Alice Smith, sku=LAPTOP, quantity=2, paymentReference=PAY-1], message=]
-...
+Order outcome: ServiceResponse[success=true, body=OrderConfirmation[orderId=ORD-1, customerId=C-1, customerName=Alice Smith, sku=LAPTOP, quantity=2, paymentReference=PAY-1], message=]
+Placing an order that should be rejected because of stock
+-> order.placeOrder payload={amount=499.0, customerId=C-2, quantity=50, sku=PHONE}
+-> customer.getCustomer payload={customerId=C-2}
+<- customer.getCustomer success=true in 0 ms
+-> inventory.checkStock payload={sku=PHONE, quantity=50}
+<- inventory.checkStock success=true in 0 ms
+<- order.placeOrder success=false in 0 ms
 Order outcome: ServiceResponse[success=false, body=null, message=Order rejected: insufficient stock for PHONE]
+Addressing a service that is not registered
 No service registered under 'shipping'
 Bus outcome: ServiceResponse[success=false, body=null, message=No such service: shipping]
--> order.placeOrder payload={amount=899.0, quantity=1, sku=LAPTOP, customerId=C-1}
-...
+Placing an order anonymously, the bus should deny access to payment
+-> order.placeOrder payload={amount=899.0, customerId=C-1, quantity=1, sku=LAPTOP}
+-> customer.getCustomer payload={customerId=C-1}
+<- customer.getCustomer success=true in 0 ms
+-> inventory.checkStock payload={sku=LAPTOP, quantity=1}
+<- inventory.checkStock success=true in 0 ms
+-> inventory.reserve payload={sku=LAPTOP, quantity=1}
+<- inventory.reserve success=true in 0 ms
 Access denied to payment.charge for anonymous caller
+-> inventory.release payload={sku=LAPTOP, quantity=1}
+<- inventory.release success=true in 0 ms
 <- order.placeOrder success=false in 0 ms
 Order outcome: ServiceResponse[success=false, body=null, message=Order rejected: Access denied to payment]
 ```
 
-## Class diagram
-
-See [service-oriented-architecture.urm.puml](./etc/service-oriented-architecture.urm.puml) for the PlantUML class diagram.
-
 ## When to Use the Service-Oriented Architecture Pattern in Java
 
 * Several applications or departments need to share the same business capabilities, such as customer, billing or inventory functions.

service-oriented-architecture/etc/service-oriented-architecture.urm.png

@@ -43,10 +43,9 @@ package com.iluwatar.soa {
     + allows(request : ServiceRequest) : boolean
   }
   class Customer {
-    + Customer(id : String, name : String, email : String)
+    + Customer(id : String, name : String)
     + id() : String
     + name() : String
-    + email() : String
   }
   class CustomerService {
     + NAME : String {static}
@@ -55,6 +54,7 @@ package com.iluwatar.soa {
     + CustomerService(customers : Map<String, Customer>)
     + name() : String
     + handle(request : ServiceRequest) : ServiceResponse
+    - getCustomer(customerId : String) : ServiceResponse
   }
   class InventoryService {
     + NAME : String {static}
@@ -63,6 +63,9 @@ package com.iluwatar.soa {
     + InventoryService(initialStock : Map<String, Integer>)
     + name() : String
     + handle(request : ServiceRequest) : ServiceResponse
+    - checkStock(sku : String, quantity : int) : ServiceResponse
+    - reserve(sku : String, quantity : int) : ServiceResponse
+    - release(sku : String, quantity : int) : ServiceResponse
   }
   class PaymentService {
     + NAME : String {static}
@@ -72,6 +75,7 @@ package com.iluwatar.soa {
     + PaymentService(creditLimit : double)
     + name() : String
     + handle(request : ServiceRequest) : ServiceResponse
+    - charge(customerId : String, amount : double) : ServiceResponse
   }
   class OrderService {
     + NAME : String {static}
@@ -80,10 +84,12 @@ package com.iluwatar.soa {
     + OrderService(bus : ServiceBus)
     + name() : String
     + handle(request : ServiceRequest) : ServiceResponse
+    - placeOrder(request : ServiceRequest) : ServiceResponse
   }
   class OrderConfirmation {
-    + OrderConfirmation(orderId : String, customerName : String, sku : String, quantity : int, paymentReference : String)
+    + OrderConfirmation(orderId : String, customerId : String, customerName : String, sku : String, quantity : int, paymentReference : String)
     + orderId() : String
+    + customerId() : String
     + customerName() : String
     + sku() : String
     + quantity() : int

service-oriented-architecture/etc/service-oriented-architecture.urm.puml

@@ -43,8 +43,8 @@
  *       isolates consumers from provider failures
  *   <li>{@link AccessPolicy}: security as a cross-cutting concern, enforced by the bus so that the
  *       services themselves contain no security code
- *   <li>{@link CustomerService}, {@link InventoryService}, {@link PaymentService}: stateless
- *       enterprise services that each own one business capability
+ *   <li>{@link CustomerService}, {@link InventoryService}, {@link PaymentService}: enterprise
+ *       services that each own one business capability and keep no per-conversation session state
  *   <li>{@link OrderService}: a composite service that orchestrates the others through the bus
  * </ul>
  *

service-oriented-architecture/src/main/java/com/iluwatar/soa/App.java

@@ -29,6 +29,5 @@
  *
  * @param id the customer identifier
  * @param name the display name
- * @param email the contact address
  */
-public record Customer(String id, String name, String email) {}
+public record Customer(String id, String name) {}

service-oriented-architecture/src/main/java/com/iluwatar/soa/Customer.java

@@ -45,8 +45,8 @@ public class CustomerService implements Service {
   public CustomerService() {
     this(
         Map.of(
-            "C-1", new Customer("C-1", "Alice Smith", "alice@example.com"),
-            "C-2", new Customer("C-2", "Bob Jones", "bob@example.com")));
+            "C-1", new Customer("C-1", "Alice Smith"),
+            "C-2", new Customer("C-2", "Bob Jones")));
   }
 
   /** Creates the service backed by the given customers. */

service-oriented-architecture/src/main/java/com/iluwatar/soa/CustomerService.java

@@ -38,6 +38,8 @@
  *       available
  *   <li>{@code reserve} with {@code sku} and {@code quantity} takes the quantity out of stock and
  *       returns the remaining amount
+ *   <li>{@code release} with {@code sku} and {@code quantity} puts a reserved quantity back into
+ *       stock and returns the remaining amount, compensating a reservation that cannot be completed
  * </ul>
  */
 public class InventoryService implements Service {
@@ -68,15 +70,23 @@ public ServiceResponse handle(ServiceRequest request) {
           request.param("sku", String.class), request.param("quantity", Integer.class));
       case "reserve" -> reserve(
           request.param("sku", String.class), request.param("quantity", Integer.class));
+      case "release" -> release(
+          request.param("sku", String.class), request.param("quantity", Integer.class));
       default -> ServiceResponse.error("Unknown operation: " + request.operation());
     };
   }
 
   private ServiceResponse checkStock(String sku, int quantity) {
+    if (quantity <= 0) {
+      return ServiceResponse.error("Quantity must be positive: " + quantity);
+    }
     return ServiceResponse.ok(stock.getOrDefault(sku, 0) >= quantity);
   }
 
   private ServiceResponse reserve(String sku, int quantity) {
+    if (quantity <= 0) {
+      return ServiceResponse.error("Quantity must be positive: " + quantity);
+    }
     var reserved = new AtomicBoolean();
     var remaining =
         stock.computeIfPresent(
@@ -99,4 +109,15 @@ private ServiceResponse reserve(String sku, int quantity) {
     }
     return ServiceResponse.ok(remaining);
   }
+
+  private ServiceResponse release(String sku, int quantity) {
+    if (quantity <= 0) {
+      return ServiceResponse.error("Quantity must be positive: " + quantity);
+    }
+    var remaining = stock.computeIfPresent(sku, (key, available) -> available + quantity);
+    if (remaining == null) {
+      return ServiceResponse.error("Unknown sku: " + sku);
+    }
+    return ServiceResponse.ok(remaining);
+  }
 }

service-oriented-architecture/src/main/java/com/iluwatar/soa/InventoryService.java

@@ -37,6 +37,10 @@
  * credential so that the bus can authorise each downstream call, and composes the responses. This
  * is how SOA builds higher level services out of reusable lower level ones.
  *
+ * <p>There is no distributed transaction spanning the services, so the order service compensates
+ * instead: it reserves the stock before it charges the customer and releases the reservation again
+ * when the charge fails.
+ *
  * <p>Operations:
  *
  * <ul>
@@ -60,13 +64,19 @@ public class OrderService implements Service {
    * The result of a successfully placed order.
    *
    * @param orderId the generated order identifier
+   * @param customerId the identifier of the ordering customer
    * @param customerName the name of the ordering customer
    * @param sku the ordered product
    * @param quantity the ordered quantity
    * @param paymentReference the reference returned by the payment service
    */
   public record OrderConfirmation(
-      String orderId, String customerName, String sku, int quantity, String paymentReference) {}
+      String orderId,
+      String customerId,
+      String customerName,
+      String sku,
+      int quantity,
+      String paymentReference) {}
 
   @Override
   public String name() {
@@ -96,26 +106,20 @@ private ServiceResponse placeOrder(ServiceRequest request) {
       return ServiceResponse.error("Order rejected: " + customer.message());
     }
 
+    // This read is kept to illustrate service composition, not as a guard: reserve re-checks the
+    // stock atomically, so the order stays correct even though the level can change in between.
     var stock =
         bus.send(
             new ServiceRequest(
                 INVENTORY_SERVICE,
                 "checkStock",
                 Map.of("sku", sku, "quantity", quantity),
                 credential));
-    if (!stock.success() || !Boolean.TRUE.equals(stock.body())) {
-      return ServiceResponse.error("Order rejected: insufficient stock for " + sku);
+    if (!stock.success()) {
+      return ServiceResponse.error("Order rejected: " + stock.message());
     }
-
-    var payment =
-        bus.send(
-            new ServiceRequest(
-                PAYMENT_SERVICE,
-                "charge",
-                Map.of("customerId", customerId, "amount", amount),
-                credential));
-    if (!payment.success()) {
-      return ServiceResponse.error("Order rejected: " + payment.message());
+    if (!Boolean.TRUE.equals(stock.body())) {
+      return ServiceResponse.error("Order rejected: insufficient stock for " + sku);
     }
 
     var reservation =
@@ -129,10 +133,26 @@ private ServiceResponse placeOrder(ServiceRequest request) {
       return ServiceResponse.error("Order rejected: " + reservation.message());
     }
 
+    var payment =
+        bus.send(
+            new ServiceRequest(
+                PAYMENT_SERVICE,
+                "charge",
+                Map.of("customerId", customerId, "amount", amount),
+                credential));
+    if (!payment.success()) {
+      bus.send(
+          new ServiceRequest(
+              INVENTORY_SERVICE, "release", Map.of("sku", sku, "quantity", quantity), credential));
+      return ServiceResponse.error("Order rejected: " + payment.message());
+    }
+
+    var orderingCustomer = (Customer) customer.body();
     var confirmation =
         new OrderConfirmation(
             "ORD-" + sequence.incrementAndGet(),
-            ((Customer) customer.body()).name(),
+            orderingCustomer.id(),
+            orderingCustomer.name(),
             sku,
             quantity,
             (String) payment.body());