content: /**
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.aurora.common.zookeeper;
  
  import java.net.InetSocketAddress;
  import java.util.Map;
  
  /**
   * A service that uses master election to only allow a single service instance to be active amongst
   * a set of potential servers at a time.
   */
  public interface SingletonService {
  
    /**
     * Indicates an error attempting to lead a group of servers.
     */
    class LeadException extends Exception {
      public LeadException(String message, Throwable cause) {
        super(message, cause);
      }
    }
  
    /**
     * Indicates an error attempting to advertise leadership of a group of servers.
     */
    class AdvertiseException extends Exception {
      public AdvertiseException(String message) {
        super(message);
      }
  
      public AdvertiseException(String message, Throwable cause) {
        super(message, cause);
      }
    }
  
    /**
     * Indicates an error attempting to leave a group of servers, abdicating leadership of the group.
     */
    class LeaveException extends Exception {
      public LeaveException(String message, Throwable cause) {
        super(message, cause);
      }
    }
  
    /**
     * Attempts to lead the singleton service.
     *
     * @param endpoint The primary endpoint to register as a leader candidate in the service.
     * @param additionalEndpoints Additional endpoints that are available on the host.
     * @param listener Handler to call when the candidate is elected or defeated.
     * @throws LeadException If there was a problem joining or watching the ZooKeeper group.
     * @throws InterruptedException If the thread watching/joining the group was interrupted.
     */
    void lead(
        InetSocketAddress endpoint,
        Map<String, InetSocketAddress> additionalEndpoints,
        LeadershipListener listener)
        throws LeadException, InterruptedException;
  
    /**
     * A listener to be notified of changes in the leadership status.
     * Implementers should be careful to avoid blocking operations in these callbacks.
     */
    interface LeadershipListener {
  
      /**
       * Notifies the listener that is is current leader.
       *
       * @param control A controller handle to advertise and/or leave advertised presence.
       */
      void onLeading(LeaderControl control);
  
      /**
       * Notifies the listener that it is no longer leader.
       */
      void onDefeated();
    }
  
    /**
     * A controller for the state of the leader.  This will be provided to the leader upon election,
     * which allows the leader to decide when to advertise as leader of the server set and terminate
     * leadership at will.
     */
    interface LeaderControl {
  
      /**
       * Advertises the leader's server presence to clients.
       *
       * @throws AdvertiseException If there was an error advertising the singleton leader to clients
       *     of the server set.
       * @throws InterruptedException If interrupted while advertising.
       */
      void advertise() throws AdvertiseException, InterruptedException;
  
      /**
       * Leaves candidacy for leadership, removing advertised server presence if applicable.
       *
       * @throws LeaveException If the leader's status could not be updated or there was an error
       *     abdicating server set leadership.
       */
      void leave() throws LeaveException;
    }
  }
  