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.io.retry.Idempotent;
024    import org.apache.hadoop.security.AccessControlException;
025    import org.apache.hadoop.security.KerberosInfo;
026    
027    import 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
039    public 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    }