ratpack.server.ReloadInformant Maven / Gradle / Ivy
Show all versions of ratpack-core Show documentation
/*
* Copyright 2015 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.server;
import ratpack.registry.Registry;
/**
* Informs when the server should be reloaded, during {@link ServerConfig#isDevelopment() development}.
*
* During development mode, all reload informants present in the server registry will be asked if the server should reload before serving each request.
* The term “reload” here specifically refers to rebuilding the server definition by re-executing the function given to the {@link RatpackServer#of(ratpack.func.Action)} method that defined the server.
*
* Reload informants will never be queried concurrently so can be safely stateful.
* Calls to {@link #shouldReload(ratpack.registry.Registry)} are serialised for any given informant, and informants are queried in sequence.
*
* Reload informants are queried in the order they are returned by the server registry.
* If an informant indicates that the server should reload, no further informants will be queried.
*
* As reload informants are queried for every request, it is sometimes desirable to internally use some kind of polling technique internally to avoid creating too much overhead.
* However, implementations do not need to be too performance sensitive as reload informants only apply during development.
*
* Reload informants are never queried when not in development mode.
* It is completely benign for informants to be in the server registry when not in development.
*
* Below shows a contrived reload informant that simply asks that the server reload on every other request.
*
{@code
* import ratpack.server.ReloadInformant;
* import ratpack.server.ServerConfig;
* import ratpack.test.embed.EmbeddedApp;
* import ratpack.registry.Registry;
*
* import static org.junit.Assert.assertEquals;
*
* public class Example {
* static class ReloadEveryOtherRequest implements ReloadInformant {
* private int i = 0;
*
* public boolean shouldReload(Registry registry) {
* return ++i % 2 == 0;
* }
*
* public String toString() {
* return "every other request informant";
* }
* }
*
* static int counter = 0;
*
* public static void main(String... args) throws Exception {
* EmbeddedApp.of(s -> s
* .serverConfig(ServerConfig.embedded().development(true))
* .registryOf(r -> r
* .add(ReloadInformant.class, new ReloadEveryOtherRequest())
* .add(Integer.class, Example.counter++)
* )
* .handler(r -> ctx -> ctx.render(ctx.get(Integer.class).toString()))
* ).test(httpClient -> {
* assertEquals("0", httpClient.getText()); // first request never queries informants
* assertEquals("1", httpClient.getText()); // reload triggered
* assertEquals("1", httpClient.getText());
* assertEquals("2", httpClient.getText()); // reload triggered
* assertEquals("2", httpClient.getText());
* });
* }
* }
* }
*/
public interface ReloadInformant {
/**
* Whether the server should reload.
*
* @return whether the server should reload
* @param registry the server registry
*/
boolean shouldReload(Registry registry);
/**
* The description of this reload informant.
*
* This value will be logged if the informant requests a reload, indicating which informant requested a reload.
*
* @return the description of this reload informant
*/
@Override
String toString();
}