001/*-
002 * #%L
003 * Smile CDR - CDR
004 * %%
005 * Copyright (C) 2016 - 2025 Smile CDR, Inc.
006 * %%
007 * All rights reserved.
008 * #L%
009 */
010package ca.cdr.api.fhirgw.svc;
011
012import ca.cdr.api.annotations.CdrPublicAPI;
013import ca.cdr.api.fhirgw.json.GatewayOperationRouteJson;
014import ca.cdr.api.fhirgw.model.OperationRequest;
015import ca.cdr.api.fhirgw.model.OperationResponse;
016import ca.uhn.fhir.rest.api.server.IBundleProvider;
017import ca.uhn.fhir.rest.server.servlet.ServletRequestDetails;
018import org.hl7.fhir.instance.model.api.IBaseResource;
019
020import java.util.List;
021
022/**
023 * The implementer of this interface will provide the logics required to delegate and orchestrate the result of
024 * the execution of an operation on a target server.
025 */
026@CdrPublicAPI
027public interface IOperationOrchestrator extends IBaseOrchestrator<GatewayOperationRouteJson> {
028
029        /**
030         * Called by a system provider to invoke a FHIR operation which returns a single resource.
031         *
032         * @param theOperationRequest
033         * @param theRequestDetails
034         * @return usually a Parameters resource
035         */
036        IBaseResource invoke(OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
037
038        //
039
040        /**
041         * Called by a system provider to invoke a FHIR operation which returns a page of results.
042         *
043         * @param theOperationRequest
044         * @param theRequestDetails
045         * @return
046         */
047        IBundleProvider invokeBundleReturning(
048                        OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
049
050        /**
051         * Called by a system provider to invoke a graphql operation
052         *
053         * @param theOperationRequest
054         * @param theRequestDetails
055         * @param theGraphQLQuery
056         * @return
057         */
058        String invokeGraphql(
059                        OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails, String theGraphQLQuery);
060
061        /**
062         * Called by a system provider to invoke a FHIR operation on a surrogate server.  The returned OperationResponse's
063         * can be used to extract/transform target responses as per the implementer's choosing.
064         *
065         * @param theOperationRequest
066         * @param theRequestDetails
067         * @return a list of OperationResponse's
068         */
069        List<OperationResponse> invokeOperationResponseReturning(
070                        OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
071
072        /**
073         * Called by a system provider to invoke a bulk export operation on surrogate server(s).
074         * Target server response headers are consolidated into a requestDetails response header.
075         *
076         * @param theOperationRequest
077         * @param theRequestDetails
078         */
079        void invokeBulkExportOperation(OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
080
081        /**
082         * Called by a system provider to invoke a bulk export status operation on surrogate server(s).
083         * When some target servers reply `Accepted` (202) responses, an `Accepted` requestDetails response
084         * header is returned.
085         * When all target servers reply `OK` (200) responses, an `OK` requestDetails response header
086         * is returned together with target response contents consolidated into the requestDetails response content.
087         *
088         * @param theOperationRequest
089         * @param theRequestDetails
090         */
091        void invokeBulkExportStatusOperation(OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
092
093        /**
094         * Called by a system provider to invoke a proxy-link operation which distributes received links on surrogate server(s).
095         * Target server response contents are consolidated into the requestDetails response content.
096         *
097         * @param theOperationRequest
098         * @param theRequestDetails
099         */
100        void invokeProxyLinkOperation(OperationRequest theOperationRequest, ServletRequestDetails theRequestDetails);
101}