package ca.cdr.api.pub.hl7v2.out;

/*-
 * #%L
 * Smile CDR - CDR
 * %%
 * Copyright (C) 2016 - 2024 Smile CDR, Inc.
 * %%
 * All rights reserved.
 * #L%
 */

import ca.uhn.hl7v2.HL7Exception;
import ca.uhn.hl7v2.model.Message;
import ca.uhn.hl7v2.model.v25.message.*;
import ca.uhn.hl7v2.model.v25.segment.*;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.hl7.fhir.instance.model.api.IBaseResource;
import org.hl7.fhir.r4.model.*;

/**
 * This service is used to generate and populate HL7 v2.x outbound (from Smile CDR) messages using
 * information from FHIR resources as the source of data.
 * <p>
 * To create a new HL7 v2.x message to transmit, the first call should be to
 * {@link #newTarget(String, String, Class)}. You can then use methods such as
 * {@link #populateMessageAdtA01FromEncounter(IBaseResource, MappingTarget, OutboundMappingInstructions)}
 * to populate the entire message according to Smile CDR's mapping rules, or use
 * individual segment methods such as {@link #populateSegmentPidFromPatient(Patient, Encounter, PID, MappingTarget, OutboundMappingInstructions)}
 * to populate individual segments. You can also simply populate the message yourself.
 * </p>
 */
public interface IHl7V2OutboundMapperSvc {

        /**
         * Create a new {@link MappingTarget} with a target {@link Message} instance that is appropriate for the
         * given {@literal theMessageCode} and {@literal theMessageTrigger} values. The MSH segment in the message
         * is populated with initial values (which may subsequently be modified if needed), but no other segments
         * are populated.
         *
         * @param theMessageCode    The message code, e.g. <code>ADT</code>
         * @param theMessageTrigger The message trigger, e.h. <code>A01</code>
         * @param theStructureType  The HAPI-HL7v2 type class corresponding to the given code and trigger. Note that these
         *                          will often agree (e.g. Code/Type of "ADT"/"A01" should use a structure type of
         *                          {@link ADT_A01 ADT_A01.class}) but there are also many cases in the HL7 v2.x
         *                          specification where a structure type gets used for multiple triggers (e.g. Code/Type of
         *                          "ADT"/"A31" uses the structure type of {@link ADT_A05 ADT_A05.class}). At this time, an
         *                          HL7 v2.5 structure class must be used.
         * @throws IllegalArgumentException If {@literal theStructureType} is inappropriate for the given
         *                                  {@literal theMessageCode} and {@literal theMessageTrigger} values.
         */
        <T extends Message> MappingTarget<T> newTarget(
                        @Nonnull String theMessageCode, @Nonnull String theMessageTrigger, @Nonnull Class<T> theStructureType)
                        throws IllegalArgumentException;

        /**
         * Populate a complete DFT_P03 structure using a ChargeItem resource as the focal resource. This can be
         * used to create messages of type DFT^P03.
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link DFT_P03}
         */
        void populateMessageDftP03FromChargeItem(
                        @Nonnull IBaseResource theFocalChargeItem,
                        @Nonnull MappingTarget<DFT_P03> theMappingTarget,
                        OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populate a complete ORU_R01 structure using a DiagnosticReport resource as the focal resource. This can be
         * used to create messages of type ORU^R01
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ORU_R01}
         */
        void populateMessageOruR01FromDiagnosticReport(
                        @Nonnull IBaseResource theFocalDiagnosticReport,
                        @Nonnull MappingTarget<ORU_R01> theMappingTarget,
                        OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populate a complete ADT_A01 structure using an Encounter resource as the focal resource. This can be
         * used to create messages of type ADT^A01, ADT^A04
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ADT_A01}
         */
        void populateMessageAdtA01FromEncounter(
                        @Nonnull IBaseResource theFocalEncounter,
                        @Nonnull MappingTarget<ADT_A01> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete ADT_A02 structure using an Encounter resource as the focal resource. This can be
         * used to create messages of type ADT^A02
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ADT_A02}
         */
        void populateMessageAdtA02FromEncounter(
                        @Nonnull IBaseResource theFocalEncounter,
                        @Nonnull MappingTarget<ADT_A02> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete ADT_A03 structure using an Encounter resource as the focal resource. This can be
         * used to create messages of type ADT^A03
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ADT_A03}
         */
        void populateMessageAdtA03FromEncounter(
                        @Nonnull IBaseResource theFocalEncounter,
                        @Nonnull MappingTarget<ADT_A03> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete ADT_A05 structure using a Patient resource as the focal resource. This can be
         * used to create messages of type ADT^A28, ADT^A31
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theFocalPatient  A Patient resource to use as the focal resource
         * @param theMappingTarget Should contain message of type {@link ADT_A05}
         */
        void populateMessageAdtA05FromPatient(
                        @Nonnull IBaseResource theFocalPatient,
                        @Nonnull MappingTarget<ADT_A05> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populate a complete ADT_A05 structure using an Encounter resource as the focal resource. This can be
         * used to create messages of type ADT^A05, ADT^A08
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theFocalEncounter An Encounter resource to use as the focal resource
         * @param theMappingTarget  Should contain message of type {@link ADT_A05}
         */
        void populateMessageAdtA05FromEncounter(
                        @Nonnull IBaseResource theFocalEncounter,
                        @Nonnull MappingTarget<ADT_A05> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete OMG_O19 structure using a ServiceRequest resource (R4+) or a ProcedureRequest resource (DSTU3)
         * as the focal resource. This can be used to create messages of type OMG^O19.
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link OMG_O19}
         */
        void populateMessageOmgO19FromServiceRequest(
                        @Nonnull IBaseResource theFocalServiceRequest,
                        @Nonnull MappingTarget<OMG_O19> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete ORM_O01 structure using a ServiceRequest resource (R4+) or a ProcedureRequest resource (DSTU3)
         * as the focal resource. This can be used to create messages of type ORM^O01.
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ORM_O01}
         */
        void populateMessageOrmO01FromServiceRequest(
                        @Nonnull IBaseResource theFocalServiceRequest,
                        @Nonnull MappingTarget<ORM_O01> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions)
                        throws HL7Exception;

        /**
         * Populate a complete ORU_R01 structure using a ServiceRequest resource (R4+) or a ProcedureRequest resource (DSTU3)
         * as the focal resource. This can be used to create messages of type ORU^R01.
         * <p>
         * This method attempts to populate the entire message structure using values from the focal
         * resource as well as from other resources that are referenced directly or indirectly from the
         * focal resource.
         * </p>
         *
         * @param theMappingTarget Should contain message of type {@link ORU_R01}
         */
        void populateMessageOruR01FromServiceRequest(
                        @Nonnull IBaseResource theFocalServiceRequest,
                        @Nonnull MappingTarget<ORU_R01> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates an ROL segment using a single {@literal Encounter.participant} instance.
         * Because {@literal Encounter.participant} is a repeating field, an index must also
         * be passed in.
         *
         * @param theEncounter                 The source Encounter to draw values from.
         * @param theEncounterParticipantIndex The index of the {@literal Encounter.participant} repetition to draw values from (0-indexed).
         * @param theRol                       The ROL segment to populate.
         * @param theMappingTarget             The target object. This is only used to store any warnings or errors generated as
         *                                     a part of the mapping.
         */
        void populateSegmentRolFromEncounterParticipant(
                        @Nonnull Encounter theEncounter,
                        int theEncounterParticipantIndex,
                        @Nonnull ROL theRol,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates an AL1 segment using values from an AllergyIntolerance resource instance.
         *
         * @param theAllergyIntolerance The source Coverage to draw values from.
         * @param theSetId              The set ID to populate in AL1-1, or {@literal null}.
         * @param theAl1                The AL1 segment to populate
         * @param theMappingTarget      The target object. This is only used to store any warnings or errors generated as
         *                              a part of the mapping.
         */
        void populateSegmentAl1FromAllergyIntolerance(
                        @Nonnull AllergyIntolerance theAllergyIntolerance,
                        @Nullable Integer theSetId,
                        @Nonnull AL1 theAl1,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a pair of IN1 and IN2 segments using values from a Coverage resource instance.
         *
         * @param theCoverage      The source Coverage to draw values from.
         * @param theIn1           The IN1 segment to populate
         * @param theIn2           The IN2 segment to populate
         * @param theMappingTarget The target object. This is only used to store any warnings or errors generated as
         *                         a part of the mapping.
         */
        void populateSegmentIn1In2FromInsurance(
                        Coverage theCoverage,
                        IN1 theIn1,
                        IN2 theIn2,
                        MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a PR1 segment using values from a Procedure resource instance.
         *
         * @param theProcedure     The source Procedure to draw values from.
         * @param thePr1           The PR1 segment to populate
         * @param theMappingTarget The target object. This is only used to store any warnings or errors generated as
         *                         a part of the mapping.
         */
        void populateSegmentPr1FromProcedure(
                        Procedure theProcedure,
                        PR1 thePr1,
                        MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates an NK1 segment using a single {@literal Patient.contact} instance.
         * Because {@literal Patient.context} is a repeating field, an index must also
         * be passed in.
         *
         * @param theEncounter               The source Encounter to draw values from.
         * @param theEncounterConditionIndex The index of the {@literal Encounter.condition} repetition to draw values from (0-indexed).
         * @param theMappingTarget           The target object. This is only used to store any warnings or errors generated as
         *                                   a part of the mapping.
         * @param theDg1                     The DG1 segment to populate.
         */
        void populateSegmentDg1FromEncounterCondition(
                        Encounter theEncounter,
                        int theEncounterConditionIndex,
                        DG1 theDg1,
                        MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates an NK1 segment using a single {@literal Patient.contact} instance.
         * Because {@literal Patient.context} is a repeating field, an index must also
         * be passed in.
         *
         * @param thePatient             The source Patient to draw values from.
         * @param thePatientContactIndex The index of the {@literal Patient.contact} repetition to draw values from (0-indexed).
         * @param theNk1                 The NK1 segment to populate.
         * @param theMappingTarget       The target object. This is only used to store any warnings or errors generated as
         *                               a part of the mapping.
         */
        void populateSegmentNk1FromPatientContact(
                        @Nonnull Patient thePatient,
                        int thePatientContactIndex,
                        @Nonnull NK1 theNk1,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a PID segment using information from a Patient resource and optionally an Encounter resource.
         *
         * @param theSubject         The subject patient.
         * @param theEncounterOrNull The focal encounter, or {@literal null}.
         * @param thePid             The PID segment to populate.
         * @param theMappingTarget   The target object. This is only used to store any warnings or errors generated as
         *                           a part of the mapping.
         */
        void populateSegmentPidFromPatient(
                        @Nonnull Patient theSubject,
                        @Nullable Encounter theEncounterOrNull,
                        @Nonnull PID thePid,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a PD1 segment using information from a Patient resource.
         *
         * @param theSubject       The subject patient.
         * @param thePd1           The PD1 segment to populate.
         * @param theMappingTarget The target object. This is only used to store any warnings or errors generated as
         *                         a part of the mapping.
         */
        void populateSegmentPd1FromPatient(
                        @Nonnull Patient theSubject,
                        @Nonnull PD1 thePd1,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a PV1 segment using information from an Encounter resource.
         *
         * @param theEncounter     The encounter resource.
         * @param thePv1           The PV1 segment to populate.
         * @param theMappingTarget The target object. This is only used to store any warnings or errors generated as
         *                         a part of the mapping.
         */
        void populateSegmentPv1FromEncounter(
                        @Nonnull Encounter theEncounter,
                        @Nonnull PV1 thePv1,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);

        /**
         * Populates a PV2 segment using information from an Encounter resource.
         *
         * @param theEncounter     The source Encounter to draw values from.
         * @param thePv2           The PV2 segment to populate.
         * @param theMappingTarget The target object. This is only used to store any warnings or errors generated as
         *                         a part of the mapping.
         */
        void populateSegmentPv2FromEncounter(
                        @Nonnull Encounter theEncounter,
                        @Nonnull PV2 thePv2,
                        @Nonnull MappingTarget<?> theMappingTarget,
                        @Nonnull OutboundMappingInstructions theOutboundMappingInstructions);
}