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 */ 018package org.apache.hadoop.ha; 019 020import org.apache.hadoop.classification.InterfaceAudience; 021import org.apache.hadoop.classification.InterfaceStability; 022import org.apache.hadoop.fs.CommonConfigurationKeys; 023import org.apache.hadoop.io.retry.Idempotent; 024import org.apache.hadoop.security.AccessControlException; 025import org.apache.hadoop.security.KerberosInfo; 026 027import java.io.IOException; 028 029/** 030 * Protocol interface that provides High Availability related primitives to 031 * monitor and fail-over the service. 032 * 033 * This interface could be used by HA frameworks to manage the service. 034 */ 035@KerberosInfo( 036 serverPrincipal=CommonConfigurationKeys.HADOOP_SECURITY_SERVICE_USER_NAME_KEY) 037@InterfaceAudience.Public 038@InterfaceStability.Evolving 039public interface HAServiceProtocol { 040 /** 041 * Initial version of the protocol 042 */ 043 public static final long versionID = 1L; 044 045 /** 046 * An HA service may be in active or standby state. During startup, it is in 047 * an unknown INITIALIZING state. During shutdown, it is in the STOPPING state 048 * and can no longer return to active/standby states. 049 */ 050 public enum HAServiceState { 051 INITIALIZING("initializing"), 052 ACTIVE("active"), 053 STANDBY("standby"), 054 STOPPING("stopping"); 055 056 private String name; 057 058 HAServiceState(String name) { 059 this.name = name; 060 } 061 062 @Override 063 public String toString() { 064 return name; 065 } 066 } 067 068 public static enum RequestSource { 069 REQUEST_BY_USER, 070 REQUEST_BY_USER_FORCED, 071 REQUEST_BY_ZKFC; 072 } 073 074 /** 075 * Information describing the source for a request to change state. 076 * This is used to differentiate requests from automatic vs CLI 077 * failover controllers, and in the future may include epoch 078 * information. 079 */ 080 public static class StateChangeRequestInfo { 081 private final RequestSource source; 082 083 public StateChangeRequestInfo(RequestSource source) { 084 super(); 085 this.source = source; 086 } 087 088 public RequestSource getSource() { 089 return source; 090 } 091 } 092 093 /** 094 * Monitor the health of service. This periodically called by the HA 095 * frameworks to monitor the health of the service. 096 * 097 * Service is expected to perform checks to ensure it is functional. 098 * If the service is not healthy due to failure or partial failure, 099 * 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 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 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 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 162 public HAServiceStatus getServiceStatus() throws AccessControlException, 163 IOException; 164}