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    }