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.net.pool;
018    
019    import com.google.common.collect.ImmutableSet;
020    
021    /**
022     * A host set that can be monitored for changes.
023     *
024     * @param <T> The type that is used to identify members of the host set.
025     *
026     * @author William Farner
027     */
028    public interface DynamicHostSet<T> {
029    
030      /**
031       * Registers a monitor to receive change notices for this server set as long as this jvm process
032       * is alive.  Blocks until the initial server set can be gathered and delivered to the monitor.
033       * The monitor will be notified if the membership set or parameters of existing members have
034       * changed.
035       *
036       * @param monitor the server set monitor to call back when the host set changes
037       * @throws MonitorException if there is a problem monitoring the host set
038       */
039      public void monitor(final HostChangeMonitor<T> monitor) throws MonitorException;
040    
041      /**
042       * An interface to an object that is interested in receiving notification whenever the host set
043       * changes.
044       */
045      public static interface HostChangeMonitor<T> {
046    
047        /**
048         * Called when either the available set of services changes (when a service dies or a new
049         * instance comes on-line) or when an existing service advertises a status or health change.
050         *
051         * @param hostSet the current set of available ServiceInstances
052         */
053        void onChange(ImmutableSet<T> hostSet);
054      }
055    
056      public static class MonitorException extends Exception {
057        public MonitorException(String msg) {
058          super(msg);
059        }
060    
061        public MonitorException(String msg, Throwable cause) {
062          super(msg, cause);
063        }
064      }
065    }