/*-
 * #%L
 * Smile CDR - CDR
 * %%
 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
 * %%
 * All rights reserved.
 * #L%
 */
package ca.cdr.api.camel;

import ca.cdr.api.model.enm.TransactionLogBodyTypeEnum;
import ca.cdr.api.model.enm.TransactionLogOutcomeEnum;
import ca.cdr.api.model.enm.TransactionLogStepTypeEnum;
import ca.cdr.api.model.json.TransactionLogStepJson;
import ca.cdr.api.transactionlog.ITransactionLogCommonSettings;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.apache.camel.Exchange;
import org.apache.commons.lang3.tuple.Pair;

import java.util.List;
import java.util.Optional;

public interface ICamelProcessorTxLogHelper {

        /**
         * Requests to include message body in the transaction log step
         * Default value is true
         */
        String TX_LOG_PARAM_SHOW_BODY = "showMsgBody";

        /**
         * If transaction logging was initiated (smile:txLogStart procedure, present before current procedure in
         * route), adds a log step to the transaction log. The step outcome is FAIL if the exchange has failed,
         * otherwise SUCCESS.
         * @param theExchange           the camel exchange
         * @param theProcedureName  the log-producing procedure name
         */
        void addStepIfTxLogActive(@Nonnull Exchange theExchange, @Nonnull String theProcedureName);

        /**
         * If transaction logging was initiated (smile:txLogStart procedure, present before current procedure in
         * route), adds step from provider to the transaction log.
         * <p>
         * If the exchange has failed, each step's outcome is set to FAIL. Otherwise an outcome already set on a
         * step is kept, and a step without an outcome is set to SUCCESS.
         * @param theExchange           the camel exchange
         * @param theStepsProvider  the provider of the corresponding transaction log steps
         */
        void addStepIfTxLogActive(@Nonnull Exchange theExchange, @Nonnull ITxLogStepsProvider theStepsProvider);

        /**
         * If transaction logging was initiated (smile:txLogStart procedure, present before current procedure in
         * route), adds the list of steps to the transaction log.
         * <p>
         * If the exchange has failed, each step's outcome is set to FAIL. Otherwise an outcome already set on a
         * step is kept, and a step without an outcome is set to SUCCESS.
         * @param theExchange  the camel exchange
         * @param theLogSteps  the log steps to be added to the transaction log
         */
        void addStepIfTxLogActive(@Nonnull Exchange theExchange, @Nonnull List<TransactionLogStepJson> theLogSteps);

        /**
         * Builds a new transaction log step from provided exchange properties and parameters.
         * The step outcome is left unset; {@link #addStepIfTxLogActive(Exchange, List)} or
         * {@link #addStepIfTxLogActive(Exchange, ITxLogStepsProvider)} sets it when the step is added.
         * @param theExchange           the camel exchange
         * @param theLogStepType        the transaction log step type
         * @param theBodyAndType        A Pair containing the body and the body type or null
         * @return the built transaction log step
         */
        @Nonnull
        TransactionLogStepJson buildTxLogStep(
                        @Nonnull Exchange theExchange,
                        @Nonnull TransactionLogStepTypeEnum theLogStepType,
                        @Nullable Pair<String, TransactionLogBodyTypeEnum> theBodyAndType);

        /**
         * @deprecated use {@link ICamelProcessorTxLogHelper#buildTxLogStep(Exchange, TransactionLogStepTypeEnum, Pair)}
         * Builds a new transaction log step considering received exchange properties and parameters.
         * @param theExchange           the camel exchange
         * @param theLogStepType        the transaction log step type
         * @param theBodyAndType        A Pair containing the body and the body type or null
         * @param theOutcome            Ignored.
         * @return the built transaction log step
         */
        @Deprecated
        @Nonnull
        default TransactionLogStepJson buildTxLogStep(
                        @Nonnull Exchange theExchange,
                        @Nonnull TransactionLogStepTypeEnum theLogStepType,
                        @Nullable Pair<String, TransactionLogBodyTypeEnum> theBodyAndType,
                        @Nullable @SuppressWarnings("unused") TransactionLogOutcomeEnum theOutcome) {
                return buildTxLogStep(theExchange, theLogStepType, theBodyAndType);
        }

        /**
         * Builds a string containing the received procedure name, including the module id if present in the exchange
         * @param theExchange           the camel exchange
         * @param theProcedureName  the log-producing procedure name
         * @return a string with the built executing procedure URI
         */
        @Nonnull
        String getRequestUrl(@Nonnull Exchange theExchange, @Nonnull String theProcedureName);

        /**
         * Informs if 'showMsgBody' parameter is present
         * @param theExchange           the camel exchange
         * @return boolean indicating if 'showMsgBody' parameter is present
         */
        boolean isTxLogShowBody(@Nonnull Exchange theExchange);

        /**
         * informs if a transaction log is active for the route
         * @param theExchange the camel exchange
         * @return boolean indicating if transaction log is active for the route
         */
        boolean isTxLogStarted(@Nonnull Exchange theExchange);

        /**
         * Requests transaction log initiation for the route
         * @param theExchange the camel exchange
         */
        void startTxLog(@Nonnull Exchange theExchange);

        /**
         * Requests transaction log initiation for the route. This initiates the log before the route is invoked, allowing
         * the caller to add entries to the log before passing control to Camel. The transaction log wil not auto-commit when
         * the route finishes, allowing the caller to continue adding entries after the Camel invocation returns.
         * The log will only commit once **both** the route is complete and the caller has called
         * {@link #manualCommitTxLog(Exchange)}
         * @param theExchange the camel exchange
         */
        void startTxLogForManualCommit(@Nonnull Exchange theExchange);

        /**
         * Commits the transaction log to configured writers
         * @param theExchange the camel exchange
         */
        void commitTxLog(@Nonnull Exchange theExchange);

        /**
         * Allows a transaction log that was initiated with {@link #startTxLogForManualCommit(Exchange)} to commit.
         * The log may not commit immediately if the route is still processing (async mode).
         * @param theExchange the camel exchange
         */
        void manualCommitTxLog(@Nonnull Exchange theExchange);

        /**
         * Discards current transaction logging and marks logging not initiated for the route
         * @param theExchange the camel exchange
         */
        void clearTxLog(@Nonnull Exchange theExchange);

        /**
         * Returns the settings associated with this writer. Event sources can use this to optimize whether to
         * include specific elements in their log entries.
         */
        @Nonnull
        ITransactionLogCommonSettings getSettings();

        /**
         * Obtain a value stored in the exchange request details map
         *
         * @param theKey the key for referencing the object to extract from the request details map
         * @param theExchange the camel exchange encapsulating the request details map
         * @return the value stored in the exchange request details map, or null if not found
         */
        @Nullable
        <T> T getPropertyFromRequestDetails(@Nonnull String theKey, @Nonnull Exchange theExchange);

        /**
         * Store a key/value in the exchange request details map
         *
         * @param theKey the key that will reference the object being stored in request details map
         * @param theValue the object being stored in request details map, or null to remove the key
         * @param theExchange the camel exchange encapsulating the request details map
         */
        void addPropertyToRequestDetails(@Nonnull String theKey, @Nullable Object theValue, @Nonnull Exchange theExchange);

        /**
         * Returns the current transaction log guid for the given exchange.
         *
         * NB: it's not enough to start a transaction; a step must be added
         * before a tx guid is generated.
         * If no step has been added, an empty optional will be returned.
         *
         * @param theExchange - the exchange
         * @return - the txlog guid, or an empty Optional if no steps have been
         *                              added yet.
         */
        @Nonnull
        Optional<String> getCurrentTxLogGuid(@Nonnull Exchange theExchange);
}