ExecutionLogRepository.java

package org.fenixedu.bennu.scheduler.log;

import java.util.Optional;
import java.util.stream.Stream;

/**
 * A log repository is responsible for storing and retrieving execution logs for scheduler tasks.
 * 
 * @author João Carvalho (joao.pedro.carvalho@tecnico.ulisboa.pt)
 *
 */
public interface ExecutionLogRepository {

    /**
     * Stores the updated version of the task log for the given execution.
     * 
     * @param log
     *            The execution log to store
     */
    public void update(ExecutionLog log);

    /**
     * Stores a new execution of a given task. This method differs from the {@link #update(ExecutionLog)} method, in that it may
     * used to update the repository's index.
     * 
     * @param log
     *            The new execution log to store
     */
    public void newExecution(ExecutionLog log);

    /**
     * Appends the given text to the task log for the given execution.
     * 
     * @param log
     *            The execution log for which the text is to be appended
     * @param text
     *            The text to be appended
     */
    public void appendTaskLog(ExecutionLog log, String text);

    /**
     * Stores the given file to the task execution related to the given {@link ExecutionLog}.
     * 
     * @param log
     *            The execution log for which this file is to be stored
     * @param fileName
     *            The name of the file to store
     * @param contents
     *            The contents to store
     * @param append
     *            Whether the contents should be appended or replace the potentially existing file
     */
    public void storeFile(ExecutionLog log, String fileName, byte[] contents, boolean append);

    /**
     * Returns the latest execution of every task that has been stored in this repository. This acts as an index for all task
     * executions.
     * 
     * The size of the returned stream is bound by the number of different tasks run in the system.
     * 
     * @return
     *         The latest execution of all tasks stored in the repository
     */
    public Stream<ExecutionLog> latest();

    /**
     * Returns a {@link Stream} containing the execution logs for the given task, up to {@code max} elements. If a start id is
     * provided, the logs will start with the one with the given id, otherwise, the latest executions are returned.
     * 
     * @param taskName
     *            The name of the task for which to retrieve the logs
     * @param startId
     *            The optional task id for which to start returning the logs. If empty, the latest executions are returned, if
     *            invalid, an empty stream is returned.
     * @param max
     *            The maximum number of elements to return
     * @return
     *         The {@code max} latest executions for the given task
     */
    public Stream<ExecutionLog> executionsFor(String taskName, Optional<String> startId, int max);

    /**
     * Returns the log generated by CronTask's {@code taskLog} method, from the given task with the given execution id, if it is
     * present on the repository. Otherwise, returns an empty {@link Optional}.
     * 
     * @param taskName
     *            The name of the task for which to retrieve the log
     * @param id
     *            The identifier of the execution for which to retrieve the log
     * @return
     *         The contents of the task log, may be empty
     */
    public Optional<String> getTaskLog(String taskName, String id);

    /**
     * Retrieves the file with the given name, generated by the execution of the given task with the given ID, if it is found.
     * Otherwise, returns an empty {@link Optional}.
     * 
     * @param taskName
     *            The name of the task for which to retrieve the file
     * @param id
     *            The identifier of the execution for which to retrieve the file
     * @param file
     *            The filename to be retrieved
     * @return
     *         The contents of the requested file, may be empty
     */
    public Optional<byte[]> getFile(String taskName, String id, String file);

    /**
     * Returns the {@link ExecutionLog} for the given task execution, by task name and execution id, if it exists in the
     * repository. Otherwise, returns an empty {@link Optional}.
     * 
     * @param taskName
     *            The name of the task for which to retrieve the log
     * @param id
     *            The identifier of the execution for which to retrieve the log
     * @return
     *         The execution log for the given id, may be empty
     */
    public Optional<ExecutionLog> getLog(String taskName, String id);

}