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 @Override
060 public String toString() {
061 return name;
062 }
063 }
064
065 public static enum RequestSource {
066 REQUEST_BY_USER,
067 REQUEST_BY_USER_FORCED,
068 REQUEST_BY_ZKFC;
069 }
070
071 /**
072 * Information describing the source for a request to change state.
073 * This is used to differentiate requests from automatic vs CLI
074 * failover controllers, and in the future may include epoch
075 * information.
076 */
077 public static class StateChangeRequestInfo {
078 private final RequestSource source;
079
080 public StateChangeRequestInfo(RequestSource source) {
081 super();
082 this.source = source;
083 }
084
085 public RequestSource getSource() {
086 return source;
087 }
088 }
089
090 /**
091 * Monitor the health of service. This periodically called by the HA
092 * frameworks to monitor the health of the service.
093 *
094 * Service is expected to perform checks to ensure it is functional.
095 * If the service is not healthy due to failure or partial failure,
096 * it is expected to throw {@link HealthCheckFailedException}.
097 * The definition of service not healthy is left to the service.
098 *
099 * Note that when health check of an Active service fails,
100 * failover to standby may be done.
101 *
102 * @throws HealthCheckFailedException
103 * if the health check of a service fails.
104 * @throws AccessControlException
105 * if access is denied.
106 * @throws IOException
107 * if other errors happen
108 */
109 public void monitorHealth() throws HealthCheckFailedException,
110 AccessControlException,
111 IOException;
112
113 /**
114 * Request service to transition to active state. No operation, if the
115 * service is already in active state.
116 *
117 * @throws ServiceFailedException
118 * if transition from standby to active fails.
119 * @throws AccessControlException
120 * if access is denied.
121 * @throws IOException
122 * if other errors happen
123 */
124 public void transitionToActive(StateChangeRequestInfo reqInfo)
125 throws ServiceFailedException,
126 AccessControlException,
127 IOException;
128
129 /**
130 * Request service to transition to standby state. No operation, if the
131 * service is already in standby state.
132 *
133 * @throws ServiceFailedException
134 * if transition from active to standby fails.
135 * @throws AccessControlException
136 * if access is denied.
137 * @throws IOException
138 * if other errors happen
139 */
140 public void transitionToStandby(StateChangeRequestInfo reqInfo)
141 throws ServiceFailedException,
142 AccessControlException,
143 IOException;
144
145 /**
146 * Return the current status of the service. The status indicates
147 * the current <em>state</em> (e.g ACTIVE/STANDBY) as well as
148 * some additional information. {@see HAServiceStatus}
149 *
150 * @throws AccessControlException
151 * if access is denied.
152 * @throws IOException
153 * if other errors happen
154 */
155 public HAServiceStatus getServiceStatus() throws AccessControlException,
156 IOException;
157 }