io.evitadb.api.task.TaskStatus Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of evita_api Show documentation
Show all versions of evita_api Show documentation
Module contains external API of the evitaDB.
The newest version!
/*
*
* _ _ ____ ____
* _____ _(_) |_ __ _| _ \| __ )
* / _ \ \ / / | __/ _` | | | | _ \
* | __/\ V /| | || (_| | |_| | |_) |
* \___| \_/ |_|\__\__,_|____/|____/
*
* Copyright (c) 2024
*
* Licensed under the Business Source License, Version 1.1 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://github.com/FgForrest/evitaDB/blob/master/LICENSE
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.evitadb.api.task;
import io.evitadb.exception.EvitaError;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.io.PrintWriter;
import java.io.Serializable;
import java.io.StringWriter;
import java.time.OffsetDateTime;
import java.util.EnumSet;
import java.util.UUID;
import java.util.concurrent.CancellationException;
/**
* This record provides the status of a task, including telemetry information and access to its progress, settings,
* and result.
*
* @param taskType The name of the task (short class name).
* @param taskName The human readable name of the task.
* @param taskId The unique identifier of the task.
* @param catalogName The name of the catalog that the task belongs to (may be NULL if the task is not bound to any particular catalog).
* @param issued The time when the task was issued.
* @param started The time when the task was started.
* @param finished The time when the task was finished.
* @param progress The progress of the task (0-100).
* @param settings The settings of the task.
* @param result The result of the task.
* @param exceptionWithStackTrace The exception with stack trace if the task failed.
* @author Jan Novotný ([email protected]), FG Forrest a.s. (c) 2024
*/
public record TaskStatus(
@Nonnull String taskType,
@Nonnull String taskName,
@Nonnull UUID taskId,
@Nullable String catalogName,
@Nonnull OffsetDateTime issued,
@Nullable OffsetDateTime started,
@Nullable OffsetDateTime finished,
int progress,
@Nonnull S settings,
@Nullable T result,
@Nullable String publicExceptionMessage,
@Nullable String exceptionWithStackTrace,
@Nonnull EnumSet traits
) implements Serializable {
/**
* Returns the shortened state of the task.
*
* @return The state of the task.
*/
@Nonnull
public TaskSimplifiedState simplifiedState() {
if (exceptionWithStackTrace != null || publicExceptionMessage != null) {
return TaskSimplifiedState.FAILED;
} else if (finished != null) {
return TaskSimplifiedState.FINISHED;
} else if (started != null) {
return TaskSimplifiedState.RUNNING;
} else {
return TaskSimplifiedState.QUEUED;
}
}
/**
* Returns new instance of {@link TaskStatus} with updated progress.
*
* @param progress The new progress of the task.
* @return The new instance of {@link TaskStatus} with updated progress.
*/
@Nonnull
public TaskStatus updateProgress(int progress) {
if (progress != this.progress) {
return new TaskStatus<>(
this.taskType,
this.taskName,
this.taskId,
this.catalogName,
this.issued,
this.started,
this.finished,
progress,
this.settings,
this.result,
this.publicExceptionMessage,
this.exceptionWithStackTrace,
this.traits
);
} else {
return this;
}
}
/**
* Returns new instance of {@link TaskStatus} with updated started time and progress.
*
* @return The new instance of {@link TaskStatus} with updated started time and progress.
*/
@Nonnull
public TaskStatus transitionToStarted() {
return new TaskStatus<>(
this.taskType,
this.taskName,
this.taskId,
this.catalogName,
this.issued,
OffsetDateTime.now(),
null,
0,
this.settings,
this.result,
this.publicExceptionMessage,
this.exceptionWithStackTrace,
this.traits
);
}
/**
* Returns new instance of {@link TaskStatus} with updated finished time and result.
*
* @param result The result of the task.
* @return The new instance of {@link TaskStatus} with updated finished time and result.
*/
@Nonnull
public TaskStatus transitionToFinished(@Nullable T result) {
return new TaskStatus<>(
this.taskType,
this.taskName,
this.taskId,
this.catalogName,
this.issued,
this.started,
OffsetDateTime.now(),
100,
this.settings,
result,
null,
null,
this.traits
);
}
/**
* Returns new instance of {@link TaskStatus} with updated exception.
*
* @param exception The exception that caused the task to fail.
* @return The new instance of {@link TaskStatus} with updated exception.
*/
@Nonnull
public TaskStatus transitionToFailed(@Nonnull Throwable exception) {
// copy the stack trace
final StringWriter sw = new StringWriter(512);
exception.printStackTrace(new PrintWriter(sw));
final String publicException;
if (exception instanceof EvitaError evitaError) {
publicException = evitaError.getPublicMessage();
} else if (exception instanceof CancellationException) {
publicException = "Task was cancelled.";
} else {
publicException = "Task failed for unknown reasons.";
}
return new TaskStatus<>(
this.taskType,
this.taskName,
this.taskId,
this.catalogName,
this.issued,
this.started,
OffsetDateTime.now(),
100,
this.settings,
null,
publicException,
exception.getClass().getName() + ": " + exception.getMessage() + "\n" + sw,
this.traits
);
}
/**
* State aggregates the possible states of a task into a simple enumeration.
*/
public enum TaskSimplifiedState {
/**
* Task is waiting in the queue to be executed.
*/
QUEUED,
/**
* Task is currently running.
*/
RUNNING,
/**
* Task has finished successfully.
*/
FINISHED,
/**
* Task has failed.
*/
FAILED
}
/**
* Enum describes traits of a {@link ServerTask} task.
*
* @author Jan Novotný ([email protected]), FG Forrest a.s. (c) 2024
*/
public enum TaskTrait {
/**
* Task can be manually started by the user.
*/
CAN_BE_STARTED,
/**
* Task can be manually cancelled by the user.
*/
CAN_BE_CANCELLED,
/**
* Task needs to be manually stopped by the user (otherwise it will run indefinitely).
*/
NEEDS_TO_BE_STOPPED
}
}