001    // =================================================================================================
002    // Copyright 2011 Twitter, Inc.
003    // -------------------------------------------------------------------------------------------------
004    // Licensed under the Apache License, Version 2.0 (the "License");
005    // you may not use this work except in compliance with the License.
006    // You may obtain a copy of the License in the LICENSE file, or at:
007    //
008    //  http://www.apache.org/licenses/LICENSE-2.0
009    //
010    // Unless required by applicable law or agreed to in writing, software
011    // distributed under the License is distributed on an "AS IS" BASIS,
012    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013    // See the License for the specific language governing permissions and
014    // limitations under the License.
015    // =================================================================================================
016    
017    package com.twitter.common.zookeeper;
018    
019    import com.twitter.common.net.pool.DynamicHostSet;
020    import com.twitter.common.zookeeper.Group.JoinException;
021    import com.twitter.thrift.ServiceInstance;
022    import com.twitter.thrift.Status;
023    
024    import java.net.InetSocketAddress;
025    import java.util.Map;
026    
027    /**
028     * A logical set of servers registered in ZooKeeper.  Intended to be used by both servers in a
029     * common service and their clients.
030     *
031     * TODO(William Farner): Explore decoupling this from thrift.
032     *
033     * @author William Farner
034     */
035    public interface ServerSet extends DynamicHostSet<ServiceInstance> {
036    
037      /**
038       * Attempts to join a server set for this logical service group.
039       *
040       * @param endpoint the primary service endpoint
041       * @param additionalEndpoints and additional endpoints keyed by their logical name
042       * @param status the current service status
043       * @return an EndpointStatus object that allows the endpoint to adjust its status
044       * @throws JoinException if there was a problem joining the server set
045       * @throws InterruptedException if interrupted while waiting to join the server set
046       */
047      public EndpointStatus join(InetSocketAddress endpoint,
048          Map<String, InetSocketAddress> additionalEndpoints, Status status)
049          throws JoinException, InterruptedException;
050    
051      /**
052       * A handle to a service endpoint's status data that allows updating it to track current events.
053       */
054      public interface EndpointStatus {
055    
056        /**
057         * Attempts to update the status of the service endpoint associated with this endpoint.  If the
058         * {@code status} is {@link Status#DEAD} then the endpoint will be removed from the server set.
059         *
060         * @param status the current status of the endpoint
061         * @throws UpdateException if there was a problem writing the update
062         */
063        void update(Status status) throws UpdateException;
064      }
065    
066      /**
067       * Indicates an error updating a service's status information.
068       */
069      public static class UpdateException extends Exception {
070        public UpdateException(String message, Throwable cause) {
071          super(message, cause);
072        }
073      }
074    }