001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 package org.apache.hadoop.ha;
019
020 import org.apache.hadoop.classification.InterfaceAudience;
021 import org.apache.hadoop.classification.InterfaceStability;
022 import org.apache.hadoop.fs.CommonConfigurationKeys;
023 import org.apache.hadoop.security.AccessControlException;
024 import org.apache.hadoop.security.KerberosInfo;
025
026 import java.io.IOException;
027
028 /**
029 * Protocol interface that provides High Availability related primitives to
030 * monitor and fail-over the service.
031 *
032 * This interface could be used by HA frameworks to manage the service.
033 */
034 @KerberosInfo(
035 serverPrincipal=CommonConfigurationKeys.HADOOP_SECURITY_SERVICE_USER_NAME_KEY)
036 @InterfaceAudience.Public
037 @InterfaceStability.Evolving
038 public interface HAServiceProtocol {
039 /**
040 * Initial version of the protocol
041 */
042 public static final long versionID = 1L;
043
044 /**
045 * An HA service may be in active or standby state. During
046 * startup, it is in an unknown INITIALIZING state.
047 */
048 public enum HAServiceState {
049 INITIALIZING("initializing"),
050 ACTIVE("active"),
051 STANDBY("standby");
052
053 private String name;
054
055 HAServiceState(String name) {
056 this.name = name;
057 }
058
059 public String toString() {
060 return name;
061 }
062 }
063
064 /**
065 * Monitor the health of service. This periodically called by the HA
066 * frameworks to monitor the health of the service.
067 *
068 * Service is expected to perform checks to ensure it is functional.
069 * If the service is not healthy due to failure or partial failure,
070 * it is expected to throw {@link HealthCheckFailedException}.
071 * The definition of service not healthy is left to the service.
072 *
073 * Note that when health check of an Active service fails,
074 * failover to standby may be done.
075 *
076 * @throws HealthCheckFailedException
077 * if the health check of a service fails.
078 * @throws AccessControlException
079 * if access is denied.
080 * @throws IOException
081 * if other errors happen
082 */
083 public void monitorHealth() throws HealthCheckFailedException,
084 AccessControlException,
085 IOException;
086
087 /**
088 * Request service to transition to active state. No operation, if the
089 * service is already in active state.
090 *
091 * @throws ServiceFailedException
092 * if transition from standby to active fails.
093 * @throws AccessControlException
094 * if access is denied.
095 * @throws IOException
096 * if other errors happen
097 */
098 public void transitionToActive() throws ServiceFailedException,
099 AccessControlException,
100 IOException;
101
102 /**
103 * Request service to transition to standby state. No operation, if the
104 * service is already in standby state.
105 *
106 * @throws ServiceFailedException
107 * if transition from active to standby fails.
108 * @throws AccessControlException
109 * if access is denied.
110 * @throws IOException
111 * if other errors happen
112 */
113 public void transitionToStandby() throws ServiceFailedException,
114 AccessControlException,
115 IOException;
116
117 /**
118 * Return the current status of the service. The status indicates
119 * the current <em>state</em> (e.g ACTIVE/STANDBY) as well as
120 * some additional information. {@see HAServiceStatus}
121 *
122 * @throws AccessControlException
123 * if access is denied.
124 * @throws IOException
125 * if other errors happen
126 */
127 public HAServiceStatus getServiceStatus() throws AccessControlException,
128 IOException;
129 }