Fineract Platform Documentation - Not yet released - WORK IN PROGRESS

java -Dloader.path=libs/ -jar fineract-provider.jar

        return this.toApiJsonSerializer.serialize(result);
    }

    @PUT
    @Path("{userId}")
    @Operation(summary = "Update a User", operationId = "updateUser", tags = { "Users" }, description = "Updates the user")
    @RequestBody(required = true, content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PutUsersUserIdRequest.class)))
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = UsersApiResourceSwagger.PutUsersUserIdResponse.class))) })
    @Consumes({ MediaType.APPLICATION_JSON })
    @Produces({ MediaType.APPLICATION_JSON })
    public String update(@PathParam("userId") @Parameter(description = "userId") final Long userId,
            @Parameter(hidden = true) final String apiRequestBodyAsJson) {

        final CommandWrapper commandRequest = new CommandWrapperBuilder() //
                .updateUser(userId) //
                .withJson(apiRequestBodyAsJson) //
                .build();

        final CommandProcessingResult result = this.commandsSourceWritePlatformService.logCommandSource(commandRequest);

            // permission to perform specific task.
            this.context.authenticatedUser(wrapper).validateHasPermissionTo(wrapper.getTaskPermissionName());
        }
        validateIsUpdateAllowed();

        final String json = wrapper.getJson();
        final JsonElement parsedCommand = this.fromApiJsonHelper.parse(json);
        JsonCommand command = JsonCommand.from(json, parsedCommand, this.fromApiJsonHelper, wrapper.getEntityName(), wrapper.getEntityId(),
                wrapper.getSubentityId(), wrapper.getGroupId(), wrapper.getClientId(), wrapper.getLoanId(), wrapper.getSavingsId(),
                wrapper.getTransactionId(), wrapper.getHref(), wrapper.getProductId(), wrapper.getCreditBureauId(),
                wrapper.getOrganisationCreditBureauId(), wrapper.getJobName(), wrapper.getLoanExternalId());

        return this.processAndLogCommandService.executeCommand(wrapper, command, isApprovedByChecker);
    }

    @Override
    public CommandProcessingResult approveEntry(final Long makerCheckerId) {
        final CommandSource commandSourceInput = validateMakerCheckerTransaction(makerCheckerId);
        validateIsUpdateAllowed();

        final CommandWrapper wrapper = CommandWrapper.fromExistingCommand(makerCheckerId, commandSourceInput.getActionName(),
                commandSourceInput.getEntityName(), commandSourceInput.getResourceId(), commandSourceInput.getSubResourceId(),
                commandSourceInput.getResourceGetUrl(), commandSourceInput.getProductId(), commandSourceInput.getOfficeId(),
                commandSourceInput.getGroupId(), commandSourceInput.getClientId(), commandSourceInput.getLoanId(),
                commandSourceInput.getSavingsId(), commandSourceInput.getTransactionId(), commandSourceInput.getCreditBureauId(),
                commandSourceInput.getOrganisationCreditBureauId(), commandSourceInput.getIdempotencyKey(),
                commandSourceInput.getLoanExternalId());
        final JsonElement parsedCommand = this.fromApiJsonHelper.parse(commandSourceInput.getCommandAsJson());
        final JsonCommand command = JsonCommand.fromExistingCommand(makerCheckerId, commandSourceInput.getCommandAsJson(), parsedCommand,
                this.fromApiJsonHelper, commandSourceInput.getEntityName(), commandSourceInput.getResourceId(),
                commandSourceInput.getSubResourceId(), commandSourceInput.getGroupId(), commandSourceInput.getClientId(),
                commandSourceInput.getLoanId(), commandSourceInput.getSavingsId(), commandSourceInput.getTransactionId(),
                commandSourceInput.getResourceGetUrl(), commandSourceInput.getProductId(), commandSourceInput.getCreditBureauId(),
                commandSourceInput.getOrganisationCreditBureauId(), commandSourceInput.getJobName(),
                commandSourceInput.getLoanExternalId());

        return this.processAndLogCommandService.executeCommand(wrapper, command, true);
    }

    @Transactional
    @Override
    public Long deleteEntry(final Long makerCheckerId) {

        validateMakerCheckerTransaction(makerCheckerId);
        validateIsUpdateAllowed();

        this.commandSourceRepository.deleteById(makerCheckerId);

        return makerCheckerId;
    }

    private CommandSource validateMakerCheckerTransaction(final Long makerCheckerId) {
        final CommandSource commandSource = this.commandSourceRepository.findById(makerCheckerId)
                .orElseThrow(() -> new CommandNotFoundException(makerCheckerId));
        if (!commandSource.isAwaitingApproval()) {
            throw new CommandNotAwaitingApprovalException(makerCheckerId);
        }
        AppUser appUser = this.context.authenticatedUser();
        String permissionCode = commandSource.getPermissionCode();
        appUser.validateHasCheckerPermissionTo(permissionCode);
        if (!configurationService.isSameMakerCheckerEnabled() && !appUser.isCheckerSuperUser()) {

    private final CommandSourceService commandSourceService;
    private final RetryConfigurationAssembler retryConfigurationAssembler;

    private final FineractRequestContextHolder fineractRequestContextHolder;
    private final Gson gson = GoogleGsonSerializerHelper.createSimpleGson();

    private CommandProcessingResult retryWrapper(Supplier<CommandProcessingResult> supplier) {
        try {
            if (!BatchRequestContextHolder.isEnclosingTransaction()) {
                return retryConfigurationAssembler.getRetryConfigurationForExecuteCommand().executeSupplier(supplier);
            }
            return supplier.get();
        } catch (RuntimeException e) {
            return fallbackExecuteCommand(e);
        }
    }

    @Override
    public CommandProcessingResult executeCommand(final CommandWrapper wrapper, final JsonCommand command,
            final boolean isApprovedByChecker) {
        return retryWrapper(() -> {
            // Do not store the idempotency key because of the exception handling
            setIdempotencyKeyStoreFlag(false);

            Long commandId = (Long) fineractRequestContextHolder.getAttribute(COMMAND_SOURCE_ID, null);
            boolean isRetry = commandId != null;
            boolean isEnclosingTransaction = BatchRequestContextHolder.isEnclosingTransaction();

            CommandSource commandSource = null;
            String idempotencyKey;
            if (isRetry) {
                commandSource = commandSourceService.getCommandSource(commandId);
                idempotencyKey = commandSource.getIdempotencyKey();
            } else if ((commandId = command.commandId()) != null) { // action on the command itself
                commandSource = commandSourceService.getCommandSource(commandId);
                idempotencyKey = commandSource.getIdempotencyKey();
            } else {
                idempotencyKey = idempotencyKeyResolver.resolve(wrapper);
            }
            exceptionWhenTheRequestAlreadyProcessed(wrapper, idempotencyKey, isRetry);

            AppUser user = context.authenticatedUser(wrapper);
            if (commandSource == null) {
                if (isEnclosingTransaction) {
                    commandSource = commandSourceService.getInitialCommandSource(wrapper, command, user, idempotencyKey);
                } else {
                    commandSource = commandSourceService.saveInitialNewTransaction(wrapper, command, user, idempotencyKey);
                    commandId = commandSource.getId();
                }
            }
            if (commandId != null) {
                storeCommandIdInContext(commandSource); // Store command id as a request attribute
            }

            setIdempotencyKeyStoreFlag(true);

            return executeCommand(wrapper, command, isApprovedByChecker, commandSource, user, isEnclosingTransaction);
        });
    }

    private CommandProcessingResult executeCommand(final CommandWrapper wrapper, final JsonCommand command,
            final boolean isApprovedByChecker, CommandSource commandSource, AppUser user, boolean isEnclosingTransaction) {

        final CommandProcessingResult result;
        try {
            result = commandSourceService.processCommand(findCommandHandler(wrapper), command, commandSource, user, isApprovedByChecker);
        } catch (Throwable t) { // NOSONAR

@Slf4j
@RequiredArgsConstructor
public class SynchronousCommandProcessingService implements CommandProcessingService {

    public static final String IDEMPOTENCY_KEY_STORE_FLAG = "idempotencyKeyStoreFlag";

    public static final String IDEMPOTENCY_KEY_ATTRIBUTE = "IdempotencyKeyAttribute";
    public static final String COMMAND_SOURCE_ID = "commandSourceId";
    private final PlatformSecurityContext context;
    private final ApplicationContext applicationContext;
    private final ToApiJsonSerializer<Map<String, Object>> toApiJsonSerializer;
    private final ToApiJsonSerializer<CommandProcessingResult> toApiResultJsonSerializer;
    private final ConfigurationDomainService configurationDomainService;
    private final CommandHandlerProvider commandHandlerProvider;
    private final IdempotencyKeyResolver idempotencyKeyResolver;
    private final CommandSourceService commandSourceService;
    private final RetryConfigurationAssembler retryConfigurationAssembler;

    private final FineractRequestContextHolder fineractRequestContextHolder;
    private final Gson gson = GoogleGsonSerializerHelper.createSimpleGson();

    private CommandProcessingResult retryWrapper(Supplier<CommandProcessingResult> supplier) {
        try {
            if (!BatchRequestContextHolder.isEnclosingTransaction()) {
                return retryConfigurationAssembler.getRetryConfigurationForExecuteCommand().executeSupplier(supplier);
            }
            return supplier.get();
        } catch (RuntimeException e) {
            return fallbackExecuteCommand(e);
        }
    }

    @Override
    public CommandProcessingResult executeCommand(final CommandWrapper wrapper, final JsonCommand command,
            final boolean isApprovedByChecker) {
        return retryWrapper(() -> {
            // Do not store the idempotency key because of the exception handling
            setIdempotencyKeyStoreFlag(false);

            Long commandId = (Long) fineractRequestContextHolder.getAttribute(COMMAND_SOURCE_ID, null);
            boolean isRetry = commandId != null;
            boolean isEnclosingTransaction = BatchRequestContextHolder.isEnclosingTransaction();

            CommandSource commandSource = null;
            String idempotencyKey;
            if (isRetry) {
                commandSource = commandSourceService.getCommandSource(commandId);
                idempotencyKey = commandSource.getIdempotencyKey();
            } else if ((commandId = command.commandId()) != null) { // action on the command itself
                commandSource = commandSourceService.getCommandSource(commandId);
                idempotencyKey = commandSource.getIdempotencyKey();
            } else {
                idempotencyKey = idempotencyKeyResolver.resolve(wrapper);
            }
            exceptionWhenTheRequestAlreadyProcessed(wrapper, idempotencyKey, isRetry);

            AppUser user = context.authenticatedUser(wrapper);
            if (commandSource == null) {
                if (isEnclosingTransaction) {
                    commandSource = commandSourceService.getInitialCommandSource(wrapper, command, user, idempotencyKey);
                } else {
                    commandSource = commandSourceService.saveInitialNewTransaction(wrapper, command, user, idempotencyKey);
                    commandId = commandSource.getId();
                }
            }
            if (commandId != null) {
                storeCommandIdInContext(commandSource); // Store command id as a request attribute
            }

            setIdempotencyKeyStoreFlag(true);

            return executeCommand(wrapper, command, isApprovedByChecker, commandSource, user, isEnclosingTransaction);
        });
    }

    private CommandProcessingResult executeCommand(final CommandWrapper wrapper, final JsonCommand command,
            final boolean isApprovedByChecker, CommandSource commandSource, AppUser user, boolean isEnclosingTransaction) {

        final CommandProcessingResult result;
        try {
            result = commandSourceService.processCommand(findCommandHandler(wrapper), command, commandSource, user, isApprovedByChecker);
        } catch (Throwable t) { // NOSONAR
            RuntimeException mappable = ErrorHandler.getMappable(t);
            ErrorInfo errorInfo = commandSourceService.generateErrorInfo(mappable);
            Integer statusCode = errorInfo.getStatusCode();
            commandSource.setResultStatusCode(statusCode);
            commandSource.setResult(errorInfo.getMessage());
            if (statusCode != SC_OK) {
                commandSource.setStatus(ERROR);
            }
            if (!isEnclosingTransaction) { // TODO: temporary solution
                commandSourceService.saveResultNewTransaction(commandSource);
            }
            // must not throw any exception; must persist in new transaction as the current transaction was already
            // marked as rollback
            publishHookErrorEvent(wrapper, command, errorInfo);
            throw mappable;
        }

        Retry persistenceRetry = retryConfigurationAssembler.getRetryConfigurationForCommandResultPersistence();

        try {
            CommandSource finalCommandSource = commandSource;
            AtomicInteger attemptNumber = new AtomicInteger(0);
            CommandSource savedCommandSource = persistenceRetry.executeSupplier(() -> {
                // Critical: Refetch on retry attempts (not on first attempt)
                CommandSource currentSource = finalCommandSource;
                attemptNumber.getAndIncrement();
                if (attemptNumber.get() > 1 && commandSource.getId() != null) {
                    log.info("Retrying command result save - attempt {} for command ID {}", attemptNumber, finalCommandSource.getId());
                    currentSource = commandSourceService.getCommandSource(finalCommandSource.getId());
                }

                // Update command source with results
                currentSource.setResultStatusCode(SC_OK);
                currentSource.updateForAudit(result);
                currentSource.setResult(toApiResultJsonSerializer.serializeResult(result));
                currentSource.setStatus(PROCESSED);

                // Return saved command source
                return commandSourceService.saveResultSameTransaction(currentSource);
            });

            // Command successfully saved
            storeCommandIdInContext(savedCommandSource);

        } catch (Exception e) {
            // After all retries have been exhausted
            log.error("Failed to persist command result after multiple retries for command ID {}", commandSource.getId(), e);
            throw new CommandResultPersistenceException("Failed to persist command result after multiple retries", e);
        }

        result.setRollbackTransaction(null);

        // When running inside an enclosing batch transaction, defer hook publication
        // until after the transaction commits. This prevents webhooks from firing for
        // commands that are subsequently rolled back when a later command in the batch
        // fails (e.g. a withdrawal succeeds but its fee charge fails, rolling back both).
        if (isEnclosingTransaction && TransactionSynchronizationManager.isSynchronizationActive()) {
            TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {

                @Override
                public void afterCommit() {
                    publishHookEvent(wrapper.entityName(), wrapper.actionName(), command, result);
                }
            });
        } else {
            publishHookEvent(wrapper.entityName(), wrapper.actionName(), command, result);
        }

        return result;
    }

    private void storeCommandIdInContext(CommandSource savedCommandSource) {
        if (savedCommandSource.getId() == null) {
            throw new IllegalStateException("Command source not saved");
        }
        // Idempotency filters and retry need this
        fineractRequestContextHolder.setAttribute(COMMAND_SOURCE_ID, savedCommandSource.getId());
    }

    private void publishHookErrorEvent(CommandWrapper wrapper, JsonCommand command, ErrorInfo errorInfo) {
        try {
            publishHookEvent(wrapper.entityName(), wrapper.actionName(), command, gson.toJson(errorInfo));
        } catch (Exception e) {
            log.error("Failed to publish hook error event for entity: {}, action: {}", wrapper.entityName(), wrapper.actionName(), e);
        }
    }

    private void exceptionWhenTheRequestAlreadyProcessed(CommandWrapper wrapper, String idempotencyKey, boolean retry) {
        CommandSource command = commandSourceService.findCommandSource(wrapper, idempotencyKey);
        if (command == null) {
            return;
        }
        CommandProcessingResultType status = CommandProcessingResultType.fromInt(command.getStatus());
        switch (status) {
            case UNDER_PROCESSING -> {
                Class<?> lastExecutionExceptionClass = retryConfigurationAssembler.getLastException();
                if (lastExecutionExceptionClass == null
                        || IdempotentCommandProcessUnderProcessingException.class.isAssignableFrom(lastExecutionExceptionClass)) {
                    throw new IdempotentCommandProcessUnderProcessingException(wrapper, idempotencyKey);
                }
            }
            case PROCESSED -> throw new IdempotentCommandProcessSucceedException(wrapper, idempotencyKey, command);
            case ERROR -> {
                if (!retry) {
                    throw new IdempotentCommandProcessFailedException(wrapper, idempotencyKey, command);
                }
            }
            default -> {
            }
        }
    }

    private void setIdempotencyKeyStoreFlag(boolean flag) {
        fineractRequestContextHolder.setAttribute(IDEMPOTENCY_KEY_STORE_FLAG, flag);
    }

    public CommandProcessingResult fallbackExecuteCommand(Exception e) {
        throw ErrorHandler.getMappable(e);
    }

    private NewCommandSourceHandler findCommandHandler(final CommandWrapper wrapper) {
        NewCommandSourceHandler handler;

        if (wrapper.isDatatableResource()) {
            if (wrapper.isCreateDatatable()) {
                handler = applicationContext.getBean("createDatatableCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isDeleteDatatable()) {
                handler = applicationContext.getBean("deleteDatatableCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isUpdateDatatable()) {
                handler = applicationContext.getBean("updateDatatableCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isCreate()) {
                handler = applicationContext.getBean("createDatatableEntryCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isUpdateMultiple()) {
                handler = applicationContext.getBean("updateOneToManyDatatableEntryCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isUpdateOneToOne()) {
                handler = applicationContext.getBean("updateOneToOneDatatableEntryCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isDeleteMultiple()) {
                handler = applicationContext.getBean("deleteOneToManyDatatableEntryCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isDeleteOneToOne()) {
                handler = applicationContext.getBean("deleteOneToOneDatatableEntryCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isRegisterDatatable()) {
                handler = applicationContext.getBean("registerDatatableCommandHandler", NewCommandSourceHandler.class);
            } else {
                throw new UnsupportedCommandException(wrapper.commandName());
            }
        } else if (wrapper.isNoteResource()) {
            if (wrapper.isCreate()) {
                handler = applicationContext.getBean("createNoteCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isUpdate()) {
                handler = applicationContext.getBean("updateNoteCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isDelete()) {
                handler = applicationContext.getBean("deleteNoteCommandHandler", NewCommandSourceHandler.class);
            } else {
                throw new UnsupportedCommandException(wrapper.commandName());
            }
        } else if (wrapper.isSurveyResource()) {
            if (wrapper.isRegisterSurvey()) {
                handler = applicationContext.getBean("registerSurveyCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isFullFilSurvey()) {
                handler = applicationContext.getBean("fullFilSurveyCommandHandler", NewCommandSourceHandler.class);
            } else {
                throw new UnsupportedCommandException(wrapper.commandName());
            }
        } else if (wrapper.isLoanDisburseDetailResource()) {
            if (wrapper.isUpdateDisbursementDate()) {
                handler = applicationContext.getBean("updateLoanDisburseDateCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.addAndDeleteDisbursementDetails()) {
                handler = applicationContext.getBean("addAndDeleteLoanDisburseDetailsCommandHandler", NewCommandSourceHandler.class);
            } else {
                throw new UnsupportedCommandException(wrapper.commandName());
            }
        } else if (wrapper.isInterestPauseResource()) {
            if (wrapper.isInterestPauseCreateResource()) {
                handler = applicationContext.getBean("createInterestPauseCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isInterestPauseUpdateResource()) {
                handler = applicationContext.getBean("updateInterestPauseCommandHandler", NewCommandSourceHandler.class);
            } else if (wrapper.isInterestPauseDeleteResource()) {
                handler = applicationContext.getBean("deleteInterestPauseCommandHandler", NewCommandSourceHandler.class);
            } else {
                throw new UnsupportedCommandException(wrapper.commandName());
            }
        } else {
            handler = commandHandlerProvider.getHandler(wrapper.entityName(), wrapper.actionName());
        }

        return handler;
    }

    @Override
    public boolean validateRollbackCommand(final CommandWrapper commandWrapper, final AppUser user) {
        user.validateHasPermissionTo(commandWrapper.getTaskPermissionName());
        boolean isMakerChecker = configurationDomainService.isMakerCheckerEnabledForTask(commandWrapper.taskPermissionName());
        return isMakerChecker && !user.isCheckerSuperUser();
    }

    protected void publishHookEvent(final String entityName, final String actionName, JsonCommand command, final Object result) {
        try {
            final AppUser appUser = context.authenticatedUser(CommandWrapper.wrap(actionName, entityName, null, null));

            final HookEventSource hookEventSource = new HookEventSource(entityName, actionName);

            // TODO: Add support for publishing array events
            if (command.json() != null) {
                Type type = new TypeToken<Map<String, Object>>() {

                }.getType();

                Map<String, Object> myMap;

                try {
                    myMap = gson.fromJson(command.json(), type);
                } catch (Exception e) {
                    throw new PlatformApiDataValidationException("error.msg.invalid.json", "The provided JSON is invalid.",
                            new ArrayList<>(), e);
                }

                Map<String, Object> reqmap = new HashMap<>();
                reqmap.put("entityName", entityName);
                reqmap.put("actionName", actionName);
                reqmap.put("createdBy", context.authenticatedUser().getId());
                reqmap.put("createdByName", context.authenticatedUser().getUsername());
                reqmap.put("createdByFullName", context.authenticatedUser().getDisplayName());

                reqmap.put("request", myMap);
                if (result instanceof CommandProcessingResult) {
                    CommandProcessingResult resultCopy = CommandProcessingResult
                            .fromCommandProcessingResult((CommandProcessingResult) result);

                    reqmap.put("officeId", resultCopy.getOfficeId());
                    reqmap.put("clientId", resultCopy.getClientId());
                    resultCopy.setOfficeId(null);
                    reqmap.put("response", resultCopy);
                } else if (result instanceof ErrorInfo ex) {
                    reqmap.put("status", "Exception");

                    Map<String, Object> errorMap = new HashMap<>();

                    try {
                        errorMap = gson.fromJson(ex.getMessage(), type);
                    } catch (Exception e) {
                        errorMap.put("errorMessage", ex.getMessage());
                    }

                    errorMap.put("errorCode", ex.getErrorCode());
                    errorMap.put("statusCode", ex.getStatusCode());

                    reqmap.put("response", errorMap);
                }

                reqmap.put("timestamp", Instant.now().toString());

                final String serializedResult = toApiJsonSerializer.serialize(reqmap);

                final HookEvent applicationEvent = new HookEvent(hookEventSource, serializedResult, appUser,
                        ThreadLocalContextUtil.getContext());

                applicationContext.publishEvent(applicationEvent);
            }
        } catch (Exception e) {
            log.error("Failed to publish hook event for entity: {}, action: {}", entityName, actionName, e);
        }
    }
}