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 */
018package org.apache.hadoop.hbase.conf;
019
020import java.util.Collections;
021import java.util.Set;
022import java.util.WeakHashMap;
023import org.apache.hadoop.conf.Configuration;
024import org.apache.hbase.thirdparty.com.google.common.annotations.VisibleForTesting;
025import org.apache.yetus.audience.InterfaceAudience;
026import org.apache.yetus.audience.InterfaceStability;
027import org.slf4j.Logger;
028import org.slf4j.LoggerFactory;
029
030/**
031 * Maintains the set of all the classes which would like to get notified
032 * when the Configuration is reloaded from the disk in the Online Configuration
033 * Change mechanism, which lets you update certain configuration properties
034 * on-the-fly, without having to restart the cluster.
035 *
036 * If a class has configuration properties which you would like to be able to
037 * change on-the-fly, do the following:
038 * 1. Implement the {@link ConfigurationObserver} interface. This would require
039 *    you to implement the
040 *    {@link ConfigurationObserver#onConfigurationChange(Configuration)}
041 *    method.  This is a callback that is used to notify your class' instance
042 *    that the configuration has changed. In this method, you need to check
043 *    if the new values for the properties that are of interest to your class
044 *    are different from the cached values. If yes, update them.
045 *
046 *    However, be careful with this. Certain properties might be trivially
047 *    mutable online, but others might not. Two properties might be trivially
048 *    mutable by themselves, but not when changed together. For example, if a
049 *    method uses properties "a" and "b" to make some decision, and is running
050 *    in parallel when the notifyOnChange() method updates "a", but hasn't
051 *    yet updated "b", it might make a decision on the basis of a new value of
052 *    "a", and an old value of "b". This might introduce subtle bugs. This
053 *    needs to be dealt on a case-by-case basis, and this class does not provide
054 *    any protection from such cases.
055 *
056 * 2. Register the appropriate instance of the class with the
057 *    {@link ConfigurationManager} instance, using the
058 *    {@link ConfigurationManager#registerObserver(ConfigurationObserver)}
059 *    method. Be careful not to do this in the constructor, as you might cause
060 *    the 'this' reference to escape. Use a factory method, or an initialize()
061 *    method which is called after the construction of the object.
062 *
063 * 3. Deregister the instance using the
064 *    {@link ConfigurationManager#deregisterObserver(ConfigurationObserver)}
065 *    method when it is going out of scope. In case you are not able to do that
066 *    for any reason, it is still okay, since entries for dead observers are
067 *    automatically collected during GC. But nonetheless, it is still a good
068 *    practice to deregister your observer, whenever possible.
069 */
070@InterfaceAudience.Private
071@InterfaceStability.Evolving
072public class ConfigurationManager {
073  private static final Logger LOG = LoggerFactory.getLogger(ConfigurationManager.class);
074
075  // The set of Configuration Observers. These classes would like to get
076  // notified when the configuration is reloaded from disk. This is a set
077  // constructed from a WeakHashMap, whose entries would be removed if the
078  // observer classes go out of scope.
079  private final Set<ConfigurationObserver> configurationObservers =
080      Collections.newSetFromMap(new WeakHashMap<>());
081
082  /**
083   * Register an observer class
084   * @param observer observer to be registered.
085   */
086  public void registerObserver(ConfigurationObserver observer) {
087    synchronized (configurationObservers) {
088      configurationObservers.add(observer);
089      if (observer instanceof PropagatingConfigurationObserver) {
090        ((PropagatingConfigurationObserver) observer).registerChildren(this);
091      }
092    }
093  }
094
095  /**
096   * Deregister an observer class
097   * @param observer to be deregistered.
098   */
099  public void deregisterObserver(ConfigurationObserver observer) {
100    synchronized (configurationObservers) {
101      configurationObservers.remove(observer);
102      if (observer instanceof PropagatingConfigurationObserver) {
103        ((PropagatingConfigurationObserver) observer).deregisterChildren(this);
104      }
105    }
106  }
107
108  /**
109   * The conf object has been repopulated from disk, and we have to notify
110   * all the observers that are expressed interest to do that.
111   */
112  public void notifyAllObservers(Configuration conf) {
113    LOG.info("Starting to notify all observers that config changed.");
114    synchronized (configurationObservers) {
115      for (ConfigurationObserver observer : configurationObservers) {
116        try {
117          if (observer != null) {
118            observer.onConfigurationChange(conf);
119          }
120        } catch (Throwable t) {
121          LOG.error("Encountered a throwable while notifying observers: " + " of type : " +
122              observer.getClass().getCanonicalName() + "(" + observer + ")", t);
123        }
124      }
125    }
126  }
127
128  /**
129   * @return the number of observers. 
130   */
131  public int getNumObservers() {
132    synchronized (configurationObservers) {
133      return configurationObservers.size();
134    }
135  }
136
137  /**
138   * @return true if contains the observer, for unit test only
139   */
140  @VisibleForTesting
141  public boolean containsObserver(ConfigurationObserver observer) {
142    synchronized (configurationObservers) {
143      return configurationObservers.contains(observer);
144    }
145  }
146}