ratpack.exec.ExecStarter Maven / Gradle / Ivy
/*
* Copyright 2014 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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 ratpack.exec;
import io.netty.channel.EventLoop;
import ratpack.api.NonBlocking;
import ratpack.func.Action;
import ratpack.registry.RegistrySpec;
/**
* Starts a new {@link Execution}.
*
* @see Execution#fork()
*/
public interface ExecStarter {
/**
* Specify the top level error handler for the execution.
*
* The given action will be invoked with any exceptions that are thrown and not handled.
*
{@code
* import org.junit.Assert;
* import ratpack.exec.Execution;
* import ratpack.exec.Promise;
* import ratpack.test.exec.ExecHarness;
*
* public class Example {
* public static void main(String... args) throws Exception {
* String value = ExecHarness.yieldSingle(e -> Promise.async(d ->
* Execution.fork()
* .onError(t -> d.success("global error handler"))
* .start(e1 ->
* Promise.error(new RuntimeException("bang1"))
* .then(v -> d.success("should not be called"))
* )
* )).getValue();
*
* Assert.assertEquals("global error handler", value);
* }
* }
* }
*
* @param onError the top level error handler for the execution
* @return {@code this}
*/
ExecStarter onError(Action onError);
/**
* Specifies the completion callback for the execution.
*
* The given action will effectively execute outside of the execution.
* The action is expected to be synchronous and cannot perform async operations.
* During its execution, there will be no thread bound execution or execution control.
* Any exceptions raised will be logged.
*
* This method should be used as a last resort.
*
* The action will be invoked regardless of whether the execution completed with an error or not.
* If the execution did complete with an error, the given action will be invoked after the error handler.
*
* This method is not additive.
* That is, any subsequent calls replace the previous value.
* @param onComplete the action to invoke when the execution completes.
* @return {@code this}
*/
ExecStarter onComplete(Action onComplete);
/**
* Specifies an action to be taken just before the execution starts.
*
* The action will be invoked after the execution registry has been populated.
*
* This method is not additive.
* That is, any subsequent calls replace the previous value.
* @param onStart the action to invoke just before the execution starts
* @return {@code this}
*/
ExecStarter onStart(Action onStart);
/**
* Populates the execution's registry.
*
* This method is not additive.
* That is, any subsequent calls replace the previous value.
*
* @param action the initial contents of the execution's registry.
* @return {@code this}
*/
ExecStarter register(Action action);
/**
* Specifies that the execution must run on the given event loop.
*
* If this method is not called, an event loop will be automatically assigned from the {@link ExecController#getEventLoopGroup() exec controller's event loop group}.
* It is generally not required, or desirable, to call this method.
*
* @param eventLoop the event loop to use for the execution
* @return {@code this}
*/
ExecStarter eventLoop(EventLoop eventLoop);
/**
* Starts the execution, with the given action as the initial segment.
*
* @param initialExecutionSegment the initial execution segment of the execution
*/
@NonBlocking
void start(Action initialExecutionSegment);
}