1 /**
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.apache.hadoop.ha;
19 
20 import org.apache.hadoop.classification.InterfaceAudience;
21 import org.apache.hadoop.classification.InterfaceStability;
22 import org.apache.hadoop.fs.CommonConfigurationKeys;
23 import org.apache.hadoop.io.retry.Idempotent;
24 import org.apache.hadoop.security.AccessControlException;
25 import org.apache.hadoop.security.KerberosInfo;
26 
27 import java.io.IOException;
28 
29 /**
30  * Protocol interface that provides High Availability related primitives to
31  * monitor and fail-over the service.
32  *
33  * This interface could be used by HA frameworks to manage the service.
34  */
35 @KerberosInfo(
36     serverPrincipal=CommonConfigurationKeys.HADOOP_SECURITY_SERVICE_USER_NAME_KEY)
37 @InterfaceAudience.Public
38 @InterfaceStability.Evolving
39 public interface HAServiceProtocol {
40   /**
41    * Initial version of the protocol
42    */
43   public static final long versionID = 1L;
44 
45   /**
46    * An HA service may be in active or standby state. During startup, it is in
47    * an unknown INITIALIZING state. During shutdown, it is in the STOPPING state
48    * and can no longer return to active/standby states.
49    */
50   public enum HAServiceState {
51     INITIALIZING("initializing"),
52     ACTIVE("active"),
53     STANDBY("standby"),
54     STOPPING("stopping");
55 
56     private String name;
57 
HAServiceState(String name)58     HAServiceState(String name) {
59       this.name = name;
60     }
61 
62     @Override
toString()63     public String toString() {
64       return name;
65     }
66   }
67 
68   public static enum RequestSource {
69     REQUEST_BY_USER,
70     REQUEST_BY_USER_FORCED,
71     REQUEST_BY_ZKFC;
72   }
73 
74   /**
75    * Information describing the source for a request to change state.
76    * This is used to differentiate requests from automatic vs CLI
77    * failover controllers, and in the future may include epoch
78    * information.
79    */
80   public static class StateChangeRequestInfo {
81     private final RequestSource source;
82 
StateChangeRequestInfo(RequestSource source)83     public StateChangeRequestInfo(RequestSource source) {
84       super();
85       this.source = source;
86     }
87 
getSource()88     public RequestSource getSource() {
89       return source;
90     }
91   }
92 
93   /**
94    * Monitor the health of service. This periodically called by the HA
95    * frameworks to monitor the health of the service.
96    *
97    * Service is expected to perform checks to ensure it is functional.
98    * If the service is not healthy due to failure or partial failure,
99    * it is expected to throw {@link HealthCheckFailedException}.
100    * The definition of service not healthy is left to the service.
101    *
102    * Note that when health check of an Active service fails,
103    * failover to standby may be done.
104    *
105    * @throws HealthCheckFailedException
106    *           if the health check of a service fails.
107    * @throws AccessControlException
108    *           if access is denied.
109    * @throws IOException
110    *           if other errors happen
111    */
112   @Idempotent
monitorHealth()113   public void monitorHealth() throws HealthCheckFailedException,
114                                      AccessControlException,
115                                      IOException;
116 
117   /**
118    * Request service to transition to active state. No operation, if the
119    * service is already in active state.
120    *
121    * @throws ServiceFailedException
122    *           if transition from standby to active fails.
123    * @throws AccessControlException
124    *           if access is denied.
125    * @throws IOException
126    *           if other errors happen
127    */
128   @Idempotent
transitionToActive(StateChangeRequestInfo reqInfo)129   public void transitionToActive(StateChangeRequestInfo reqInfo)
130                                    throws ServiceFailedException,
131                                           AccessControlException,
132                                           IOException;
133 
134   /**
135    * Request service to transition to standby state. No operation, if the
136    * service is already in standby state.
137    *
138    * @throws ServiceFailedException
139    *           if transition from active to standby fails.
140    * @throws AccessControlException
141    *           if access is denied.
142    * @throws IOException
143    *           if other errors happen
144    */
145   @Idempotent
transitionToStandby(StateChangeRequestInfo reqInfo)146   public void transitionToStandby(StateChangeRequestInfo reqInfo)
147                                     throws ServiceFailedException,
148                                            AccessControlException,
149                                            IOException;
150 
151   /**
152    * Return the current status of the service. The status indicates
153    * the current <em>state</em> (e.g ACTIVE/STANDBY) as well as
154    * some additional information. {@see HAServiceStatus}
155    *
156    * @throws AccessControlException
157    *           if access is denied.
158    * @throws IOException
159    *           if other errors happen
160    */
161   @Idempotent
getServiceStatus()162   public HAServiceStatus getServiceStatus() throws AccessControlException,
163                                                    IOException;
164 }
165