ratpack.service.ServiceDependencies Maven / Gradle / Ivy
/*
* Copyright 2016 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.service;
/**
* Specifies dependencies between services.
*
* When starting a server, Ratpack will extract all instances of {@link ServiceDependencies} from the server registry.
* Each will be called with a {@link ServiceDependenciesSpec spec} that they can use to define the dependencies between services.
*
* Services are guaranteed to start after and stop before their dependencies.
* Services that do not have a dependency relationship may start and stop concurrently.
* If a depended on service fails to start, the dependent service will not be started.
*
*
{@code
* import ratpack.server.RatpackServer;
* import ratpack.service.Service;
* import ratpack.service.ServiceDependencies;
* import ratpack.service.StartEvent;
* import ratpack.service.StopEvent;
*
* import java.util.ArrayList;
* import java.util.List;
*
* import static java.util.Arrays.asList;
* import static org.junit.Assert.assertEquals;
*
* public class Example {
*
* private static final List EVENTS = new ArrayList<>();
*
* private static class MyService implements Service {
*
* private final String label;
*
* public MyService(String label) {
* this.label = label;
* }
*
* public String getLabel() {
* return label;
* }
*
* {@literal @}Override
* public void onStart(StartEvent event) throws Exception {
* EVENTS.add(label + "-start");
* }
*
* {@literal @}Override
* public void onStop(StopEvent event) throws Exception {
* EVENTS.add(label + "-stop");
* }
* }
*
* public static void main(String[] args) throws Exception {
* RatpackServer server = RatpackServer.of(s -> s
* .registryOf(r -> r
* .add(new MyService("one"))
* .add(new MyService("two"))
* // service two depends on service one
* .add(ServiceDependencies.class, d -> d.dependsOn(
* MyService.class, service -> service.getLabel().equals("two"),
* MyService.class, service -> service.getLabel().equals("one")
* ))
* )
* );
*
* server.start();
* assertEquals(asList("one-start", "two-start"), EVENTS);
*
* server.stop();
* assertEquals(asList("one-start", "two-start", "two-stop", "one-stop"), EVENTS);
* }
* }
* }
*
* If dependencies between services can be declared purely via types, consider using the {@link DependsOn} annotation instead which is more concise yet equivalent.
*
* @see DependsOn
* @see ServiceDependenciesSpec
* @since 1.3
*/
public interface ServiceDependencies {
/**
* Declares service depenencies via the given spec.
*
* @param spec the spec of service dependencies
* @throws Exception any
*/
void define(ServiceDependenciesSpec spec) throws Exception;
}