View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration2.builder.combined;
18  
19  import java.util.Collection;
20  import java.util.LinkedList;
21  import java.util.Map;
22  
23  import org.apache.commons.configuration2.CombinedConfiguration;
24  import org.apache.commons.configuration2.HierarchicalConfiguration;
25  import org.apache.commons.configuration2.XMLConfiguration;
26  import org.apache.commons.configuration2.builder.BuilderParameters;
27  import org.apache.commons.configuration2.builder.ConfigurationBuilder;
28  import org.apache.commons.configuration2.builder.ReloadingFileBasedConfigurationBuilder;
29  import org.apache.commons.configuration2.ex.ConfigurationException;
30  import org.apache.commons.configuration2.reloading.CombinedReloadingController;
31  import org.apache.commons.configuration2.reloading.ReloadingController;
32  import org.apache.commons.configuration2.reloading.ReloadingControllerSupport;
33  
34  /**
35   * <p>
36   * An extension of {@code CombinedConfigurationBuilder} which also supports reloading operations.
37   * </p>
38   * <p>
39   * This class differs from its super class in the following aspects:
40   * </p>
41   * <ul>
42   * <li>A {@link ReloadingController} is created which manages all child configuration builders supporting reloading
43   * operations.</li>
44   * <li>If no {@code ConfigurationBuilder} is provided for the definition configuration, a builder with reloading support
45   * is created.</li>
46   * </ul>
47   * <p>
48   * This class can be used exactly as its super class for creating combined configurations from multiple configuration
49   * sources. In addition, the combined reloading controller managed by an instance can be used to react on changes in one
50   * of these configuration sources or in the definition configuration.
51   * </p>
52   *
53   * @since 2.0
54   */
55  public class ReloadingCombinedConfigurationBuilder extends CombinedConfigurationBuilder implements ReloadingControllerSupport {
56      /**
57       * Checks whether the passed in builder object supports reloading. If yes, its reloading controller is obtained and
58       * added to the given list.
59       *
60       * @param subControllers the list with sub controllers
61       * @param builder the builder object to be checked
62       */
63      public static void obtainReloadingController(final Collection<ReloadingController> subControllers, final Object builder) {
64          if (builder instanceof ReloadingControllerSupport) {
65              subControllers.add(((ReloadingControllerSupport) builder).getReloadingController());
66          }
67      }
68  
69      /** The reloading controller used by this builder. */
70      private ReloadingController reloadingController;
71  
72      /**
73       * Creates a new instance of {@code ReloadingCombinedConfigurationBuilder}. No parameters are set.
74       */
75      public ReloadingCombinedConfigurationBuilder() {
76      }
77  
78      /**
79       * Creates a new instance of {@code ReloadingCombinedConfigurationBuilder} and sets the specified initialization
80       * parameters.
81       *
82       * @param params a map with initialization parameters
83       */
84      public ReloadingCombinedConfigurationBuilder(final Map<String, Object> params) {
85          super(params);
86      }
87  
88      /**
89       * Creates a new instance of {@code ReloadingCombinedConfigurationBuilder} and sets the specified initialization
90       * parameters and the <em>allowFailOnInit</em> flag.
91       *
92       * @param params a map with initialization parameters
93       * @param allowFailOnInit the <em>allowFailOnInit</em> flag
94       */
95      public ReloadingCombinedConfigurationBuilder(final Map<String, Object> params, final boolean allowFailOnInit) {
96          super(params, allowFailOnInit);
97      }
98  
99      /**
100      * {@inheritDoc} This method is overridden to adapt the return type.
101      */
102     @Override
103     public ReloadingCombinedConfigurationBuilder configure(final BuilderParameters... params) {
104         super.configure(params);
105         return this;
106     }
107 
108     /**
109      * Creates the {@code ReloadingController} for this builder. This method is called after the result configuration has
110      * been created and initialized. It is called from a synchronized block. This implementation creates a
111      * {@link CombinedReloadingController}.
112      *
113      * @return the {@code ReloadingController} for this builder
114      * @throws ConfigurationException if an error occurs
115      */
116     protected ReloadingController createReloadingController() throws ConfigurationException {
117         final Collection<ReloadingController> subControllers = new LinkedList<>();
118         final ConfigurationBuilder<? extends HierarchicalConfiguration<?>> defBuilder = getDefinitionBuilder();
119         obtainReloadingController(subControllers, defBuilder);
120 
121         getChildBuilders().forEach(b -> obtainReloadingController(subControllers, b));
122 
123         final CombinedReloadingController ctrl = new CombinedReloadingController(subControllers);
124         ctrl.resetInitialReloadingState();
125         return ctrl;
126     }
127 
128     /**
129      * {@inheritDoc} This implementation creates a builder for XML configurations with reloading support.
130      */
131     @Override
132     protected ConfigurationBuilder<? extends HierarchicalConfiguration<?>> createXMLDefinitionBuilder(final BuilderParameters builderParams) {
133         return new ReloadingFileBasedConfigurationBuilder<>(XMLConfiguration.class).configure(builderParams);
134     }
135 
136     /**
137      * {@inheritDoc} This implementation makes sure that the reloading state of the managed reloading controller is reset.
138      * Note that this has to be done here and not in {@link #initResultInstance(CombinedConfiguration)} because it must be
139      * outside of a synchronized block; otherwise, a dead-lock situation can occur.
140      */
141     @Override
142     public CombinedConfiguration getConfiguration() throws ConfigurationException {
143         final CombinedConfiguration result = super.getConfiguration();
144         reloadingController.resetReloadingState();
145         return result;
146     }
147 
148     /**
149      * {@inheritDoc} This implementation returns a {@link CombinedReloadingController} which contains sub controllers for
150      * all child configuration sources with reloading support. If the definition builder supports reloading, its controller
151      * is contained, too. Note that the combined reloading controller is initialized when the result configuration is
152      * created (i.e. when calling {@code getConfiguration()} for the first time). So this method does not return a
153      * meaningful result before.
154      */
155     @Override
156     public synchronized ReloadingController getReloadingController() {
157         return reloadingController;
158     }
159 
160     /**
161      * {@inheritDoc} This implementation first calls the super method to actually initialize the result configuration. Then
162      * it creates the {@link CombinedReloadingController} for all child configuration sources with reloading support.
163      */
164     @Override
165     protected void initResultInstance(final CombinedConfiguration result) throws ConfigurationException {
166         super.initResultInstance(result);
167         if (reloadingController == null) {
168             reloadingController = createReloadingController();
169         }
170     }
171 }