Internal error reporting

Motivation

To handle internal error reporting, for example when a bends pack couldn't be loaded or a server connection couldn't be established, a system has been created. It doesn't assume a particular output where the error messages should be displayed, this ensures minimal code changes between changes in Forge version.

Interfaces

IReportOutputStream

A simple interface for printing partials of messages. Each call to 'print' is appended to the last, so as far as this interface is concerned, all 'print' calls append to the same error message.

public interface IReportOutputStream
{
    /**
     * Prints the specified text in a default style.
     * Same as calling `print(text, 0)`
     * @param text The text to be printed.
     */
    void print(String text);

    /**
     * Prints the specified text, applying optional style according to the flags.
     * @param text The text to be printed.
     * @param flags A binary OR combination of TextStyle flags.
     */
    void print(String text, int flags);
}

IErrorHandler

Whatever implements this interface should react in some way to the passed exception, preferrably print an error message to the passed stream.

@FunctionalInterface
public interface IErrorHandler<T extends Exception>
{
    void handle(IReportOutputStream stream, T exception);
}

IReportOutput

Used before and after calling an IErrorHandler.

public interface IReportOutput extends IReportOutputStream
{
    /**
     * Prepares everything necessary to start calling 'print' methods.
     */
    void beginMessage();

    /**
     * Packs up whatever's been added by 'print' methods, and outputs it.
     */
    void finishMessage();
}

IErrorReporter

Should be used whenever someone wants to report a specific Exception. The reported should be able to handle the passed in Exception.

public interface IErrorReporter
{
    <T extends Exception> void report(T exception);
}

IErrorReportRegistry

Should allow for registering handlers to react to specific Exceptitons.

public interface IErrorReportRegistry
{
    <T extends Exception> void register(Class<T> exceptionClass, IErrorHandler<T> errorHandler);
}

Example usage

The example below uses Forge implementations of the interfaces.

ReportOutput reportOutput = new ReportOutput();
ErrorReportRegistry registry = new ErrorReportRegistry(reportOutput);

// Passing the reportRegistry as a `IErrorReportRegistry` to the core so that it can register it's error handlers.
core.registerErrors(reportRegistry);

// Reacting to an exception.
reportRegistry.report(new InvalidPackFormatException("Example Pack", "Example error message"));