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