View Javadoc

1   /**
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.hadoop.hbase.conf;
19  
20  import org.apache.commons.logging.Log;
21  import org.apache.commons.logging.LogFactory;
22  import org.apache.hadoop.conf.Configuration;
23  import org.apache.hadoop.hbase.classification.InterfaceAudience;
24  import org.apache.hadoop.hbase.classification.InterfaceStability;
25  
26  import java.util.Collections;
27  import java.util.Set;
28  import java.util.WeakHashMap;
29  
30  /**
31   * Maintains the set of all the classes which would like to get notified
32   * when the Configuration is reloaded from the disk in the Online Configuration
33   * Change mechanism, which lets you update certain configuration properties
34   * on-the-fly, without having to restart the cluster.
35   *
36   * If a class has configuration properties which you would like to be able to
37   * change on-the-fly, do the following:
38   * 1. Implement the {@link ConfigurationObserver} interface. This would require
39   *    you to implement the
40   *    {@link ConfigurationObserver#onConfigurationChange(Configuration)}
41   *    method.  This is a callback that is used to notify your class' instance
42   *    that the configuration has changed. In this method, you need to check
43   *    if the new values for the properties that are of interest to your class
44   *    are different from the cached values. If yes, update them.
45   *
46   *    However, be careful with this. Certain properties might be trivially
47   *    mutable online, but others might not. Two properties might be trivially
48   *    mutable by themselves, but not when changed together. For example, if a
49   *    method uses properties "a" and "b" to make some decision, and is running
50   *    in parallel when the notifyOnChange() method updates "a", but hasn't
51   *    yet updated "b", it might make a decision on the basis of a new value of
52   *    "a", and an old value of "b". This might introduce subtle bugs. This
53   *    needs to be dealt on a case-by-case basis, and this class does not provide
54   *    any protection from such cases.
55   *
56   * 2. Register the appropriate instance of the class with the
57   *    {@link ConfigurationManager} instance, using the
58   *    {@link ConfigurationManager#registerObserver(ConfigurationObserver)}
59   *    method. For the RS side of things, the ConfigurationManager is a static
60   *    member of the {@link org.apache.hadoop.hbase.regionserver.HRegionServer}
61   *    class. Be careful not to do this in the constructor, as you might cause
62   *    the 'this' reference to escape. Use a factory method, or an initialize()
63   *    method which is called after the construction of the object.
64   *
65   * 3. Deregister the instance using the
66   *    {@link ConfigurationManager#deregisterObserver(ConfigurationObserver)}
67   *    method when it is going out of scope. In case you are not able to do that
68   *    for any reason, it is still okay, since entries for dead observers are
69   *    automatically collected during GC. But nonetheless, it is still a good
70   *    practice to deregister your observer, whenever possible.
71   *
72   */
73  @InterfaceAudience.Private
74  @InterfaceStability.Evolving
75  public class ConfigurationManager {
76    private static final Log LOG = LogFactory.getLog(ConfigurationManager.class);
77  
78    // The set of Configuration Observers. These classes would like to get
79    // notified when the configuration is reloaded from disk. This is a set
80    // constructed from a WeakHashMap, whose entries would be removed if the
81    // observer classes go out of scope.
82    private Set<ConfigurationObserver> configurationObservers =
83      Collections.newSetFromMap(new WeakHashMap<ConfigurationObserver,
84                                                Boolean>());
85  
86    /**
87     * Register an observer class
88     * @param observer
89     */
90    public void registerObserver(ConfigurationObserver observer) {
91      synchronized (configurationObservers) {
92        configurationObservers.add(observer);
93        if (observer instanceof PropagatingConfigurationObserver) {
94          ((PropagatingConfigurationObserver) observer).registerChildren(this);
95        }
96      }
97    }
98  
99    /**
100    * Deregister an observer class
101    * @param observer
102    */
103   public void deregisterObserver(ConfigurationObserver observer) {
104     synchronized (configurationObservers) {
105       configurationObservers.remove(observer);
106       if (observer instanceof PropagatingConfigurationObserver) {
107         ((PropagatingConfigurationObserver) observer).deregisterChildren(this);
108       }
109     }
110   }
111 
112   /**
113    * The conf object has been repopulated from disk, and we have to notify
114    * all the observers that are expressed interest to do that.
115    */
116   public void notifyAllObservers(Configuration conf) {
117     LOG.info("Starting to notify all observers that config changed.");
118     synchronized (configurationObservers) {
119       for (ConfigurationObserver observer : configurationObservers) {
120         try {
121           if (observer != null) {
122             observer.onConfigurationChange(conf);
123           }
124         } catch (Throwable t) {
125           LOG.error("Encountered a throwable while notifying observers: " + " of type : " +
126               observer.getClass().getCanonicalName() + "(" + observer + ")", t);
127         }
128       }
129     }
130   }
131 
132   /**
133    * @return the number of observers. 
134    */
135   public int getNumObservers() {
136     synchronized (configurationObservers) {
137       return configurationObservers.size();
138     }
139   }
140 }