/*-
 * #%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 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
         * @param theExchange           the camel exchange
         * @param theProcedureName  the log-producing procedure name
         */
        void addStepIfTxLogActive(Exchange theExchange, String theProcedureName);

        /**
         * If transaction logging was initiated (smile:txLogStart procedure, present before current procedure in
         * route), adds step from provider to the transaction log
         * @param theExchange           the camel exchange
         * @param theStepsProvider  the provider of the corresponding transaction log steps
         */
        void addStepIfTxLogActive(Exchange theExchange, ITxLogStepsProvider theStepsProvider);

        /**
         * If transaction logging was initiated (smile:txLogStart procedure, present before current procedure in
         * route), adds step from provider to the transaction log, adds the list of steps to the transaction log
         * @param theExchange  the camel exchange
         * @param theLogSteps  the log steps to be added to the transaction log
         */
        void addStepIfTxLogActive(Exchange theExchange, List<TransactionLogStepJson> theLogSteps);

        /**
         * Builds a new transaction log step from provided exchange properties and parameters.
         * If theExchange.isFailed(), the step outcome is set to FAIL, otherwise SUCCESS.
         * @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
         */
        TransactionLogStepJson buildTxLogStep(
                        Exchange theExchange,
                        TransactionLogStepTypeEnum theLogStepType,
                        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
        default TransactionLogStepJson buildTxLogStep(
                        Exchange theExchange,
                        TransactionLogStepTypeEnum theLogStepType,
                        Pair<String, TransactionLogBodyTypeEnum> theBodyAndType,
                        @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
         */
        String getRequestUrl(Exchange theExchange, String theProcedureName);

        /**
         * Informs if 'showMsgBody' parameter is present
         * @param theExchange           the camel exchange
         * @return boolean indicating if 'showMsgBody' parameter is present
         */
        boolean isTxLogShowBody(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(Exchange theExchange);

        /**
         * Requests transaction log initiation for the route
         * @param theExchange the camel exchange
         */
        void startTxLog(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(Exchange theExchange);

        /**
         * Commits the transaction log to configured writers
         * @param theExchange the camel exchange
         */
        void commitTxLog(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(Exchange theExchange);

        /**
         * Discards current transaction logging and marks logging not initiated for the route
         * @param theExchange the camel exchange
         */
        void clearTxLog(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.
         */
        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
         */
        <T> T getPropertyFromRequestDetails(String theKey, 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
         * @param theExchange the camel exchange encapsulating the request details map
         */
        void addPropertyToRequestDetails(String theKey, Object theValue, 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 (if present), or null (if no steps have been
         *                              added yet).
         */
        Optional<String> getCurrentTxLogGuid(Exchange theExchange);
}