Document the code of notification and shipping microservices

Author: BOURGUI07

notification-service/src/main/java/com/example/notification_service/config/CustomerEventConsumerConfig.java

@@ -13,6 +13,15 @@
 
 import java.util.function.Consumer;
 
+/**
+ * The Notification-Microservice gonna consume CustomerEvents
+ * so that extract the infos it need to send notifications
+ * It will receive the events wrapped into Messages
+ * will convert them into custom Records
+ * consume the Records messages, then acknowledge
+ */
+
+
 @Configuration
 @RequiredArgsConstructor
 @Slf4j

notification-service/src/main/java/com/example/notification_service/config/OrderEventConsumerConfig.java

@@ -14,6 +14,14 @@
 
 import java.util.function.Consumer;
 
+/**
+ * The Notification-Microservice gonna consume OrderEvents
+ * It will receive the events wrapped into Messages
+ * will convert them into custom Records
+ * consume the Records messages, then acknowledge
+ */
+
+
 @Configuration
 @RequiredArgsConstructor
 @Slf4j

notification-service/src/main/java/com/example/notification_service/consumer/OrderEventConsumerImpl.java

@@ -8,6 +8,10 @@
 import org.springframework.stereotype.Service;
 import reactor.core.publisher.Mono;
 
+/**
+ * Based on the order-event type, the notification-microservice gonna consume the events
+ */
+
 @Service
 @RequiredArgsConstructor
 @Slf4j

notification-service/src/main/java/com/example/notification_service/service/CustomerService.java

@@ -13,12 +13,26 @@
 
 import java.util.function.Predicate;
 
+/**
+ * Since the Customer-Microservice only implements POST requests regarding customer states
+ * then the customer-service here is responsible for saving the newlyCreatedCustomers into the DB
+ * it only save the customerId, username and email
+ */
+
+
 @Service
 @RequiredArgsConstructor
 @Slf4j
 public class CustomerService {
     private final CustomerRepo repo;
 
+    /**
+     * Received the CreatedCustomerEvent
+     * make sure the customer doesn't already exist
+     * convert the event into an entity
+     * save the entity.
+     */
+
     @Transactional
     public Mono<Void> saveCustomer(CustomerEvent.Created event) {
         return repo.existsByCustomerId(event.customerId())

notification-service/src/main/java/com/example/notification_service/service/NotificationService.java

@@ -20,6 +20,13 @@
 import java.util.function.Function;
 import java.util.function.Predicate;
 
+/**
+ * The notification-service is responsible for sending notifications
+ * as soon as an order is either created, cancelled, or completed
+ * the notification service will send messages
+ */
+
+
 @Service
 @RequiredArgsConstructor
 @Slf4j
@@ -34,6 +41,11 @@ public class NotificationService {
     private static final String CANCELLED_SUBJECT= "Order Cancelled Notification";
     private static final String COMPLETED_SUBJECT= "Order Completed Notification";
 
+    /**
+     * Here the generic message
+     * the subject, username, orderId, and the orderStatus gonna change based on the situation
+     */
+
     private static final String GENERIC_MESSAGE = """
             ==============================
             %s
@@ -74,6 +86,11 @@ private Mono<Boolean> sendEmail(String recipient, String subject, String content
     }
 
 
+    /**
+     * make sure the order with event orderId hasn't been processed before,
+     * if so raise duplicate event exception
+     * otherwise save the order while setting the status to CREATED
+     */
     private Function<OrderEvent.Created,Mono<OrderEvent.Created>> validateCreatedOrderEvent(){
         return event -> repo.existsByOrderId(event.orderId())
                 .filter(Predicate.not(b->b))
@@ -82,6 +99,11 @@ private Function<OrderEvent.Created,Mono<OrderEvent.Created>> validateCreatedOrd
                 .thenReturn(event);
     }
 
+
+    /**
+     * the order has to be of CREATED status before considering sending CANCELLED notification
+     * set the status into CANCELLED and then save the order
+     */
     private Function<OrderEvent.Cancelled,Mono<OrderEvent.Cancelled>> validateCancelledOrderEvent(){
         return event -> repo.findByOrderIdAndStatus(event.orderId(),OrderStatus.CREATED)
                 .flatMap(x -> repo.save(x.setStatus(OrderStatus.CANCELED)))
@@ -94,6 +116,11 @@ private Function<OrderEvent.Cancelled,Mono<OrderEvent.Cancelled>> validateCancel
 
     }
 
+
+    /**
+     * the order has to be of CREATED status before considering sending COMPLETED notification
+     * set the status into COMPLETED and then save the order
+     */
     private Function<OrderEvent.Completed,Mono<OrderEvent.Completed>> validateCompletedOrderEvent(){
         return event -> repo.findByOrderIdAndStatus(event.orderId(),OrderStatus.CREATED)
                 .flatMap(x -> repo.save(x.setStatus(OrderStatus.COMPLETED)))
@@ -106,7 +133,13 @@ private Function<OrderEvent.Completed,Mono<OrderEvent.Completed>> validateComple
     }
 
 
-
+    /**
+     * Receive the event
+     * make sure it hasn't been processed before
+     * then send the email to customer
+     * if the operation failed, raise emailFailure exception
+     * do nothing if either email failure or duplicate event exception were raised
+     */
     @Transactional
     public Mono<Void> sendEmailCreated(OrderEvent.Created event) {
         return validateCreatedOrderEvent().apply(event)

shipping-service/src/main/java/com/example/shipping_service/processor/OrderEventProcessorImpl.java

@@ -20,6 +20,15 @@ public class OrderEventProcessorImpl implements OrderEventProcessor {
 
     private final ShippingService service;
 
+    /**
+     * Receive the CreatedOrderEvent
+     * Convert it into shipping Request dto
+     * the shipping-service will return shipping response dto
+     * convert the latter into ReadyShippingEvent
+     * if duplicate event is raised, do nothing
+     * return DeclinedShippingEvent in case the quantity limit exceeded
+     */
+
     @Override
     public Mono<ShippingEvent> handle(OrderEvent.Created event) {
         return service.planShipping().apply(((ShippingDTO.Request) Mapper.toRequest().apply(event)))
@@ -29,13 +38,21 @@ public Mono<ShippingEvent> handle(OrderEvent.Created event) {
                 .onErrorResume(QuantityLimitException.class, ex -> Mapper.toDeclined().apply(ex, event));
     }
 
+
+    /**
+     * If the order is completed, then we have to schedule the shipping
+     */
     @Override
     public Mono<ShippingEvent> handle(OrderEvent.Completed event) {
         return service.scheduleShipping().apply(event.orderId())
                 .cast(ShippingDTO.Response.class)
                 .map(Mapper.toScheduled());
     }
 
+
+    /**
+     * cancel shipping if order is cancelled
+     */
     @Override
     public Mono<ShippingEvent> handle(OrderEvent.Cancelled event) {
         return service.cancelShipping().apply(event.orderId())

shipping-service/src/main/java/com/example/shipping_service/service/ShippingService.java

@@ -25,6 +25,17 @@
 public class ShippingService {
     private final ShippingRepo repo;
 
+    /**
+     * receive the request
+     * make sure the order hasn't bee processed before
+     * of so raise duplicate event exception
+     * also make sure the request quantity doesn't exceed the quantity limit
+     * if s raise quantityLimit exception
+     * if all went well, convert the request into entity
+     * set the entity status to PENDING
+     * save into the DB
+     * convert the saved entity into DTO
+     */
 
     public Function<ShippingDTO.Request, Mono<ShippingDTO>> planShipping() {
         return request -> {
@@ -41,12 +52,28 @@ public Function<ShippingDTO.Request, Mono<ShippingDTO>> planShipping() {
         };
     }
 
+
+    /**
+     * Receive the CancelledOrderEvent orderId
+     * to cancel the shipping, it has to have PENDING status before
+     * find the entity, set its status to CANCELLED
+     * then save into the DB
+     * finally convert the saved entity into dto
+     */
     public Function<UUID, Mono<ShippingDTO>> cancelShipping() {
         return orderId -> repo.findByOrderIdAndStatus(orderId,ShippingStatus.PENDING)
                 .flatMap(entity -> repo.save(entity.setStatus(ShippingStatus.CANCELLED)))
                 .map(Mapper.toDto());
     }
 
+
+    /**
+     * Receive the CancelledOrderEvent orderId
+     * to schedule the shipping, it has to have PENDING status before
+     * find the entity, set its status to SCHEDULED and set delivery date
+     * then save into the DB
+     * finally convert the saved entity into dto
+     */
     public Function<UUID, Mono<ShippingDTO>> scheduleShipping() {
         return orderId -> repo.findByOrderIdAndStatus(orderId,ShippingStatus.PENDING)
                 .flatMap(e -> repo.save(e.setStatus(ShippingStatus.SCHEDULED).setDeliveryDate(Instant.now().plus(Duration.ofDays(3)))))