/*
* SonarQube
* Copyright (C) 2009-2017 SonarSource SA
* mailto:info AT sonarsource DOT com
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 3 of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
package org.sonar.ce.queue;
import java.util.Collection;
import java.util.List;
/**
* Queue of pending Compute Engine tasks. Both producer and consumer actions
* are implemented.
* <p>
* This class is decoupled from the regular task type {@link org.sonar.db.ce.CeTaskTypes#REPORT}.
* </p>
*/
public interface CeQueue {
/**
* Build an instance of {@link CeTaskSubmit} required for {@link #submit(CeTaskSubmit)}. It allows
* to enforce that task ids are generated by the queue. It's used also for having access
* to the id before submitting the task to the queue.
*/
CeTaskSubmit.Builder prepareSubmit();
/**
* Submits a task to the queue. The task is processed asynchronously.
* <p>
* This method is equivalent to calling {@code massSubmit(Collections.singletonList(submission))}.
* </p>
*
* @throws IllegalStateException If submits are paused (see {@link #isSubmitPaused()})
*/
CeTask submit(CeTaskSubmit submission);
/**
* Submits multiple tasks to the queue at once. All tasks are processed asynchronously.
* <p>
* This method will perform significantly better that calling {@link #submit(CeTaskSubmit)} in a loop.
* </p>
*
* @throws IllegalStateException If submits are paused (see {@link #isSubmitPaused()})
*/
List<CeTask> massSubmit(Collection<CeTaskSubmit> submissions);
/**
* Cancels a task in status {@link org.sonar.db.ce.CeQueueDto.Status#PENDING}. An unchecked
* exception is thrown if the status is not {@link org.sonar.db.ce.CeQueueDto.Status#PENDING}.
* The method does nothing and returns {@code false} if the task does not exist.
*
* @return true if the task exists and is successfully canceled.
*/
boolean cancel(String taskUuid);
/**
* Removes all the tasks from the queue, except the tasks with status
* {@link org.sonar.db.ce.CeQueueDto.Status#IN_PROGRESS} are ignored. They are marked
* as {@link org.sonar.db.ce.CeActivityDto.Status#CANCELED} in past activity.
* This method can be called at runtime, even if workers are being executed.
*
* @return the number of canceled tasks
*/
int cancelAll();
void pauseSubmit();
void resumeSubmit();
boolean isSubmitPaused();
}