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.security.AccessControlException;
024import org.apache.hadoop.security.KerberosInfo;
025
026import 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
038public 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}