Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you 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 org.apache.hadoop.service; import org.apache.hadoop.classification.InterfaceAudience.Public; import org.apache.hadoop.classification.InterfaceStability.Evolving; import org.apache.hadoop.conf.Configuration; import java.io.Closeable; import java.io.IOException; import java.util.List; import java.util.Map; /** * Service LifeCycle. */ @Public @Evolving public interface Service extends Closeable { /** * Service states */ public enum STATE { /** Constructed but not initialized */ NOTINITED(0, "NOTINITED"), /** Initialized but not started or stopped */ INITED(1, "INITED"), /** started and not stopped */ STARTED(2, "STARTED"), /** stopped. No further state transitions are permitted */ STOPPED(3, "STOPPED"); /** * An integer value for use in array lookup and JMX interfaces. * Although {@link Enum#ordinal()} could do this, explicitly * identify the numbers gives more stability guarantees over time. */ private final int value; /** * A name of the state that can be used in messages */ private final String statename; private STATE(int value, String name) { this.value = value; this.statename = name; } /** * Get the integer value of a state * @return the numeric value of the state */ public int getValue() { return value; } /** * Get the name of a state * @return the state's name */ @Override public String toString() { return statename; } } /** * Initialize the service. * * The transition MUST be from {@link STATE#NOTINITED} to {@link STATE#INITED} * unless the operation failed and an exception was raised, in which case * {@link #stop()} MUST be invoked and the service enter the state * {@link STATE#STOPPED}. * @param config the configuration of the service * @throws RuntimeException on any failure during the operation */ void init(Configuration config); /** * Start the service. * * The transition MUST be from {@link STATE#INITED} to {@link STATE#STARTED} * unless the operation failed and an exception was raised, in which case * {@link #stop()} MUST be invoked and the service enter the state * {@link STATE#STOPPED}. * @throws RuntimeException on any failure during the operation */ void start(); /** * Stop the service. This MUST be a no-op if the service is already * in the {@link STATE#STOPPED} state. It SHOULD be a best-effort attempt * to stop all parts of the service. * * The implementation must be designed to complete regardless of the service * state, including the initialized/uninitialized state of all its internal * fields. * @throws RuntimeException on any failure during the stop operation */ void stop(); /** * A version of stop() that is designed to be usable in Java7 closure * clauses. * Implementation classes MUST relay this directly to {@link #stop()} * @throws IOException never * @throws RuntimeException on any failure during the stop operation */ void close() throws IOException; /** * Register a listener to the service state change events. * If the supplied listener is already listening to this service, * this method is a no-op. * @param listener a new listener */ void registerServiceListener(ServiceStateChangeListener listener); /** * Unregister a previously registered listener of the service state * change events. No-op if the listener is already unregistered. * @param listener the listener to unregister. */ void unregisterServiceListener(ServiceStateChangeListener listener); /** * Get the name of this service. * @return the service name */ String getName(); /** * Get the configuration of this service. * This is normally not a clone and may be manipulated, though there are no * guarantees as to what the consequences of such actions may be * @return the current configuration, unless a specific implentation chooses * otherwise. */ Configuration getConfig(); /** * Get the current service state * @return the state of the service */ STATE getServiceState(); /** * Get the service start time * @return the start time of the service. This will be zero if the service * has not yet been started. */ long getStartTime(); /** * Query to see if the service is in a specific state. * In a multi-threaded system, the state may not hold for very long. * @param state the expected state * @return true if, at the time of invocation, the service was in that state. */ boolean isInState(STATE state); /** * Get the first exception raised during the service failure. If null, * no exception was logged * @return the failure logged during a transition to the stopped state */ Throwable getFailureCause(); /** * Get the state in which the failure in {@link #getFailureCause()} occurred. * @return the state or null if there was no failure */ STATE getFailureState(); /** * Block waiting for the service to stop; uses the termination notification * object to do so. * * This method will only return after all the service stop actions * have been executed (to success or failure), or the timeout elapsed * This method can be called before the service is inited or started; this is * to eliminate any race condition with the service stopping before * this event occurs. * @param timeout timeout in milliseconds. A value of zero means "forever" * @return true iff the service stopped in the time period */ boolean waitForServiceToStop(long timeout); /** * Get a snapshot of the lifecycle history; it is a static list * @return a possibly empty but never null list of lifecycle events. */ public List<LifecycleEvent> getLifecycleHistory(); /** * Get the blockers on a service -remote dependencies * that are stopping the service from being <i>live</i>. * @return a (snapshotted) map of blocker name->description values */ public Map<String, String> getBlockers(); }