de.uka.ipd.sdq.beagle.core.failurehandling

Class FailureHandler

java.lang.Object

de.uka.ipd.sdq.beagle.core.failurehandling.FailureHandler

public final class FailureHandler
extends Object

Handler for any failures that may occur while running Beagle. Clients may obtain an instance of this class to report that an exceptional situation occurred.

Failures reported through this API may be recoverable. This means that Beagle’s execution does not have to be stopped and that there is a way to continue without or to retry the failed action. Recoverable failures are handled by recover functions that may optionally return a value to continue with after the failure.

The reaction to failures can be configured by setting a provider for FailureResolvers through setProvider(Supplier). The resolvers provided by the provider will be used when a failure is handled by this class.

Given that the class has a failure handler defined in the constant FAILURE_HANDLER, these are some usage examples:

 
 public ReturnType myMethod(ParameterType1 param1, ParameterType2 param2) {
        // code
        try {
                // code that may fail
        } catch (MyExceptionType exception) {
                final FailureReport<ReturnTyp> failure = new FailureReport<>()
                        .message("doing something with %s and %s failed", param1, param2)
                        .cause(exception)
                        .recoverable()
                        .retryWith(() -< myMethod(param1, param2));
                return FAILURE_HANDLER.handle(failure);
        }
        // more code
 }
 
 

 
 public ReturnType myMethod(ParameterType1 param1, ParameterType2 param2) {
        // code
        if (failed) {
                final FailureReport<Void> failure = new FailureReport<>()
                        .message("doing something with %s and %s failed", param1, param2)
                        .details("We tried this and that, but doing so was not possible")
                        .continueWith(this::otherMethod);
                FAILURE_HANDLER.handle(failure);
                return null;
        }
        // more code
 }
 
 

Method Summary

Modifier and Type	Method and Description
static FailureHandler	getHandler(Class<?> clientType) Creates a handler instances of clientType may report failures to.
static FailureHandler	getHandler(String clientName) Creates a handler a client identified by clientName may report failures to.
<RECOVER_TYPE> RECOVER_TYPE	handle(FailureReport<RECOVER_TYPE> report) Reports a failure to this handler and makes it take action.
static void	setProvider(Supplier<FailureResolver> provider) Sets the provider of failure resolvers.

Methods inherited from class java.lang.Object

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

Method Detail

getHandler

public static FailureHandler getHandler(String clientName)

Creates a handler a client identified by clientName may report failures to.

Parameters:

clientName - A name identifying the client that may report failures to this handler. Must not be null.

Returns:

A handler for failures of a client called clientName.

getHandler

public static FailureHandler getHandler(Class<?> clientType)

Creates a handler instances of clientType may report failures to.

Parameters:

clientType - Class of the clients that may report failures to this handler. Must not be null.

Returns:

A handler for failures of clients assignable to clientType.

setProvider

public static void setProvider(Supplier<FailureResolver> provider)

Sets the provider of failure resolvers. The provider will be used to generate a resolver when a failure is reported until another provider is set through this method.

Parameters:

provider - A factory for resolvers. Must not be null.

handle

public <RECOVER_TYPE> RECOVER_TYPE handle(FailureReport<RECOVER_TYPE> report)

Reports a failure to this handler and makes it take action. This may include calling the recover functions potentially provided through report. This method will return the value generated by the recover functions. If the report describes a non-recoverable failure, this method will not return. This method might also not return if the handler thinks it’s not appropriate to continue.

A call to this method will obtain a resolver from the provider set through setProvider(Supplier). This resolver will be called to handle the failure.

Type Parameters:

RECOVER_TYPE - The recover value’s type.

Parameters:

report - Information about the failure.

Returns:

The value the reporter should use instead of the one that was expected to be generated by the failed action. Is created by the recover functions in report.