001/*-
002 * #%L
003 * HAPI FHIR JPA Server - Batch2 Task Processor
004 * %%
005 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.batch2.api;
021
022import ca.uhn.fhir.batch2.model.JobInstance;
023import ca.uhn.fhir.batch2.model.JobInstanceStartRequest;
024import ca.uhn.fhir.batch2.model.StatusEnum;
025import ca.uhn.fhir.batch2.models.JobInstanceFetchRequest;
026import ca.uhn.fhir.jpa.batch.models.Batch2JobStartResponse;
027import ca.uhn.fhir.rest.api.server.RequestDetails;
028import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
029import ca.uhn.fhir.rest.server.exceptions.ResourceNotFoundException;
030import jakarta.annotation.Nonnull;
031import jakarta.annotation.Nullable;
032import org.springframework.data.domain.Page;
033
034import java.util.List;
035import java.util.Set;
036
037public interface IJobCoordinator {
038
039        /**
040         * Starts a new job instance
041         *
042         * @param theStartRequest The request, containing the job type and parameters
043         * @return Returns a unique ID for this job execution
044         * @throws InvalidRequestException If the request is invalid (incorrect/missing parameters, etc)
045         * @deprecated Use {@link #startInstance(RequestDetails, JobInstanceStartRequest)}
046         */
047        @Deprecated(since = "6.8.0", forRemoval = true)
048        default Batch2JobStartResponse startInstance(JobInstanceStartRequest theStartRequest)
049                        throws InvalidRequestException {
050                return startInstance(null, theStartRequest);
051        }
052
053        /**
054         * Starts a new job instance
055         *
056         * @param theRequestDetails The request details associated with the request. This will get used to validate that the
057         *                          request is appropriate for the given user, so if at all possible it should be the
058         *                          original RequestDetails from the server request.
059         * @param theStartRequest The request, containing the job type and parameters
060         * @return Returns a unique ID for this job execution
061         * @throws InvalidRequestException If the request is invalid (incorrect/missing parameters, etc)
062         */
063        Batch2JobStartResponse startInstance(RequestDetails theRequestDetails, JobInstanceStartRequest theStartRequest)
064                        throws InvalidRequestException;
065
066        /**
067         * Fetch details about a job instance
068         *
069         * @param theInstanceId The instance ID
070         * @return Returns the current instance details
071         * @throws ResourceNotFoundException If the instance ID can not be found
072         */
073        @Nonnull
074        JobInstance getInstance(String theInstanceId) throws ResourceNotFoundException;
075
076        /**
077         * Fetch all job instances
078         */
079        List<JobInstance> getInstances(int thePageSize, int thePageIndex);
080
081        /**
082         * Fetch recent job instances
083         */
084        List<JobInstance> getRecentInstances(int theCount, int theStart);
085
086        JobOperationResultJson cancelInstance(String theInstanceId) throws ResourceNotFoundException;
087
088        List<JobInstance> getInstancesbyJobDefinitionIdAndEndedStatus(
089                        String theJobDefinitionId, @Nullable Boolean theEnded, int theCount, int theStart);
090
091        /**
092         * Fetches all job instances tht meet the FetchRequest criteria
093         * @param theFetchRequest - fetch request
094         * @return - page of job instances
095         */
096        Page<JobInstance> fetchAllJobInstances(JobInstanceFetchRequest theFetchRequest);
097
098        /**
099         * Fetches all job instances by job definition id and statuses
100         */
101        List<JobInstance> getJobInstancesByJobDefinitionIdAndStatuses(
102                        String theJobDefinitionId, Set<StatusEnum> theStatuses, int theCount, int theStart);
103
104        /**
105         * Fetches all jobs by job definition id
106         */
107        List<JobInstance> getJobInstancesByJobDefinitionId(String theJobDefinitionId, int theCount, int theStart);
108}