sirius.web.tasks.ManagedTask Maven / Gradle / Ivy
Show all versions of sirius-web Show documentation
/*
* Made with all the love in the world
* by scireum in Remshalden, Germany
*
* Copyright by scireum GmbH
* http://www.scireum.de - [email protected]
*/
package sirius.web.tasks;
import sirius.kernel.commons.Tuple;
import sirius.kernel.nls.NLS;
import javax.annotation.Nullable;
import java.time.Instant;
import java.util.List;
/**
* A managed task is essentially a background job or task with some metadata attached.
*
* It can be created by {@link ManagedTasks#createManagedTaskSetup(String)} and is used to report
* potentially long running acitivities to the administrator.
*
* A managed task is created using a {@link ManagedTaskSetup}. The acutal runnable being executed uses a
* {@link ManagedTaskContext} to interact with the system. A {@link ManagedTask} is the supervisor interface
* which mainly reports the state of running tasks.
*
*/
public interface ManagedTask {
/**
* Enuemrates possible states of a task.
*/
enum State {
SCHEDULED("label-info"), RUNNING("label-success"), WARNINGS("label-warning"), TERMINATED("label-default");
private final String labelClass;
State(String labelClass) {
this.labelClass = labelClass;
}
public String getLabelClass() {
return labelClass;
}
@Override
public String toString() {
return NLS.get("ManagedTask.State." + name());
}
}
/**
* Contains the unique ID of the task.
*
* @return the unique ID of the task
*/
String getId();
/**
* Contains the unique ID of the user that started the task.
*
* @return the id of the user which started the task
*/
@Nullable
String getUserId();
/**
* Returns the name of the user that started the task.
*
* @return the name of the user that started the task
*/
@Nullable
String getUsername();
/**
* Contains the unique ID of the tenant the user who started the task belongs to if present.
*
* @return the unique ID of the tenant the user who started the task belongs to
*/
@Nullable
String getTenantId();
/**
* Returns the timestamp when the task was scheduled (started in the users eye).
*
* @return the timestamp when the task was scheduled
*/
Instant getScheduled();
/**
* Returns the timestamp when the execution of the task started.
*
* @return the timestamp when the execution of the task started
*/
@Nullable
Instant getStarted();
/**
* Returns the timestamp when the execution of the task finished.
*
* @return the timestamp when the execution of the task finished
*/
@Nullable
Instant getTerminated();
/**
* Returns a descriptive name of the task.
*
* @return a descriptive name of the task
*/
String getName();
/**
* Returns the category (executor) in which the task was started.
*
* @return the name of the executor which was used to schedule and execute the task
* @see sirius.kernel.async.Tasks#executor(String)
*/
String getCategory();
/**
* Returns the state of the task.
*
* @return the state of the task
*/
State getState();
/**
* Returns a short textual description of what the task is currently doing.
*
* @return a shot description of the tasks current state
*/
@Nullable
String getStateString();
/**
* Returns the latest log entries.
*
* The log is limited to a sane number of entries to pevent excessive memory usage.
*
* @return a list containing the last few log entries
*/
List getLastLogs();
/**
* Returns a list of all recorded performance counters.
*
* The first part of the tuple will be the name of the counter. The second will contain the counter value along with
* the avarage duration (if supplied).
*
* @return a list of tuples which contains all recorded performance counters
*/
List> getTimings();
/**
* Cancels the execution of the task.
*/
void cancel();
}