All Downloads are FREE. Search and download functionalities are using the official Maven repository.

ratpack.server.ReloadInformant Maven / Gradle / Ivy

/*
 * 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(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy