001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.health;
018
019/**
020 * Implemented by servlets that want to be told the embedded server's per-service {@link ReadinessState}, so they
021 * can react when shutdown begins (see {@link ReadinessState#onOutOfService(Object, Runnable)}).
022 *
023 * <p>
024 * The embedded-server lifecycle component (e.g. {@code JettyServerComponent}, {@code TomcatServerComponent})
025 * calls {@link #acceptReadinessState(ReadinessState)} on each auto-discovered servlet that implements this
026 * interface, before the server starts.  A typical use is closing long-lived streaming connections at the start
027 * of a graceful shutdown so the drain does not have to wait out its stop timeout for them.
028 *
029 * <h5 class='section'>Example:</h5>
030 * <p class='bjava'>
031 *    <ja>@Rest</ja>(path=<js>"/events"</js>)
032 *    <jk>public class</jk> EventsResource <jk>extends</jk> BasicRestServlet <jk>implements</jk> ReadinessStateAware {
033 *
034 *       <ja>@Override</ja> <jc>/* ReadinessStateAware *&#47;</jc>
035 *       <jk>public void</jk> acceptReadinessState(ReadinessState <jv>state</jv>) {
036 *          <jc>// Stable key: a re-publish on server restart replaces this callback instead of adding another.</jc>
037 *          <jv>state</jv>.onOutOfService(<js>"my-streams"</js>, <jk>this</jk>::closeStreams);
038 *       }
039 *
040 *       <jk>private void</jk> closeStreams() {
041 *          <jc>// End long-lived SSE/streaming responses so the graceful drain can finish.</jc>
042 *       }
043 *    }
044 * </p>
045 *
046 * @since 10.0.0
047 */
048public interface ReadinessStateAware {
049
050   /**
051    * Receives the lifecycle-owned readiness state.
052    *
053    * <p>
054    * May be called more than once (once per server start); implementations should register callbacks under a
055    * stable key so repeated calls replace rather than accumulate.
056    *
057    * @param state The per-service readiness state.  Never <jk>null</jk>.
058    */
059   void acceptReadinessState(ReadinessState state);
060}