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 }