org.fenixedu.bennu.scheduler.log

Class ExecutionLog

java.lang.Object

org.fenixedu.bennu.scheduler.log.ExecutionLog

public class ExecutionLog
extends Object

An execution log is a record containing all the relevant information about a specific execution of a task. Each execution is assigned an ID that is unique across all executions of the same task. An execution log is immutable, meaning that different snapshots of a given execution can be taken. Newer versions of log for this execution must be retrieved using the log repository. It may optionally hold the code of the task that was run, as well as the user who triggered its execution. This usage is mostly prevalent in manually-input CustomTasks.

Author:

João Carvalho (joao.pedro.carvalho@tecnico.ulisboa.pt)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExecutionLog.TaskState Represents the current state of a task.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ExecutionLog(com.google.gson.JsonObject json) Creates a new Execution Log from the provided JSON representation.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj)
Optional<String>	getCode() If this log refers to a CustomTask, the code that was run is returned.
Optional<org.joda.time.DateTime>	getEnd() If this task is in the ExecutionLog.TaskState.RUNNING state, returns an empty Optional.
Set<String>	getFiles() Returns an immutable set of all the filenames output by the task during its execution.
String	getHostname() Returns the canonical hostname of the machine that ran this task.
String	getId() Returns the unique identifier of this execution.
Optional<String>	getStackTrace() If the task is in the ExecutionLog.TaskState.RUNNING state, returns the stack trace of the execution thrown by the task, if one is present.
org.joda.time.DateTime	getStart() Returns the date in which this execution has started.
ExecutionLog.TaskState	getState() Returns the ExecutionLog.TaskState for this execution.
String	getTaskName() Returns the name of the task that this execution refers to.
Optional<String>	getUser() If this log refers to a CustomTask, the username of the user that ran the task is returned.
int	hashCode()
com.google.gson.JsonObject	json() Returns a JSON representation of this log.
static ExecutionLog	newCustomExecution(String taskName, String code, String user) Creates a new execution log for the given custom task, taking note of the code that was run, and the user who ran it.
static ExecutionLog	newExecutionFor(String taskName) Creates a new execution log for the given task, automatically assigning it a randomly-generated unique identifier.
ExecutionLog	withError(Throwable t) Creates a new ExecutionLog based on this one, marking it as failed, with the stack trace provided by the given throwable.
ExecutionLog	withFile(String filename) Creates a new ExecutionLog based on this one, with the given filename added to the list of files generated by the task.
ExecutionLog	withSuccess() Creates a new ExecutionLog based on this one, marking it as successful, ending in the moment of the method call.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExecutionLog

protected ExecutionLog(com.google.gson.JsonObject json)

Creates a new Execution Log from the provided JSON representation. The provided JSON must have been returned by another log's json() method, otherwise the results of invoking this constructor are undefined.

Parameters:

json - The JSON object containing the description of an execution log

Method Detail

newExecutionFor

public static ExecutionLog newExecutionFor(String taskName)

Creates a new execution log for the given task, automatically assigning it a randomly-generated unique identifier. The returned log is in the ExecutionLog.TaskState.RUNNING state, with the current time as the start time.

Parameters:

taskName - The name of the task that was run

Returns:

A new execution log for the given task

Throws:

NullPointerException - If the task name is null

newCustomExecution

public static ExecutionLog newCustomExecution(String taskName,
                                              String code,
                                              String user)

Creates a new execution log for the given custom task, taking note of the code that was run, and the user who ran it. Just like the newExecutionFor(String) method, the returned log is assigned a randomly-generated unique identifier, an is in the ExecutionLog.TaskState.RUNNING state, with the current time as the start time.

Parameters:

taskName - The name of the task that was run

code - The code that was run

user - The user who ran the task

Returns:

A new execution log for the given task

Throws:

NullPointerException - If either the task name, code or user is null

getId

public String getId()

Returns the unique identifier of this execution.

Returns:

The identifier of the execution

getStart

public org.joda.time.DateTime getStart()

Returns the date in which this execution has started.

Returns:

The start date for this execution

getEnd

public Optional<org.joda.time.DateTime> getEnd()

If this task is in the ExecutionLog.TaskState.RUNNING state, returns an empty Optional. Otherwise returns the date in which this execution has ended.

Returns:

The end date for this execution, may be empty

getState

public ExecutionLog.TaskState getState()

Returns the ExecutionLog.TaskState for this execution.

Returns:

The current state of this execution

getTaskName

public String getTaskName()

Returns the name of the task that this execution refers to.

Returns:

The name of the task being executed

getStackTrace

public Optional<String> getStackTrace()

If the task is in the ExecutionLog.TaskState.RUNNING state, returns the stack trace of the execution thrown by the task, if one is present. Otherwise, returns an empty Optional.

Returns:

The stack trace of the exception thrown by the task, may be empty

getFiles

public Set<String> getFiles()

Returns an immutable set of all the filenames output by the task during its execution.

Returns:

The filenames of all the files output by the task

getHostname

public String getHostname()

Returns the canonical hostname of the machine that ran this task.

Returns:

The hostname of the machine that ran the task

getCode

public Optional<String> getCode()

If this log refers to a CustomTask, the code that was run is returned. Otherwise, returns an empty Optional .

Returns:

The code that was run, may be empty

getUser

public Optional<String> getUser()

If this log refers to a CustomTask, the username of the user that ran the task is returned. Otherwise, returns an empty Optional.

Returns:

The user who ran the task, may be empty

withSuccess

public ExecutionLog withSuccess()

Creates a new ExecutionLog based on this one, marking it as successful, ending in the moment of the method call. This is typically invoked upon successful task completion, so that it may be recorded in the log repository.

Returns:

A copy of this log marked as successful

withError

public ExecutionLog withError(Throwable t)

Creates a new ExecutionLog based on this one, marking it as failed, with the stack trace provided by the given throwable. The returned log has its end date as the current date. This is typically invoked upon failed task completion, so that it may be recorded in the log repository.

Parameters:

t - The exception that caused this task to fail

Returns:

A copy of this log marked as failure

withFile

public ExecutionLog withFile(String filename)

Creates a new ExecutionLog based on this one, with the given filename added to the list of files generated by the task.

Parameters:

filename - The name of the file to be added

Returns:

A copy of this log with the added file

Throws:

NullPointerException - If the given filename was null

json

public com.google.gson.JsonObject json()

Returns a JSON representation of this log. Optional slots are only present in the returned JSON if they are non-empty.

Note: The JSON returned by this method can be used by log repositories to re-create instances of ExecutionLog from their JSON representation, via the package-protected ExecutionLog(JsonObject) constructor.

Returns:

A JSON representation of this log

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object