001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.configuration2.builder.combined;
018
019import java.util.Collection;
020import java.util.Collections;
021import java.util.Map;
022import java.util.Set;
023import java.util.stream.Collectors;
024
025import org.apache.commons.configuration2.FileBasedConfiguration;
026import org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder;
027import org.apache.commons.configuration2.builder.ReloadingFileBasedConfigurationBuilder;
028import org.apache.commons.configuration2.ex.ConfigurationException;
029import org.apache.commons.configuration2.reloading.CombinedReloadingController;
030import org.apache.commons.configuration2.reloading.ReloadingController;
031import org.apache.commons.configuration2.reloading.ReloadingControllerSupport;
032
033/**
034 * <p>
035 * A specialized {@code MultiFileConfigurationBuilder} implementation which adds support for reloading.
036 * </p>
037 * <p>
038 * This class - as its super class - allows operating on multiple configuration files whose file names are determined
039 * using a file name pattern and a {@code ConfigurationInterpolator} object. It provides the following additional
040 * features:
041 * </p>
042 * <ul>
043 * <li>Configuration builder for managed configurations have reloading support. So reloading is possible for all
044 * configuration sources loaded by this builder instance.</li>
045 * <li>A {@link ReloadingController} is provided which can be used to trigger reload checks on all managed
046 * configurations.</li>
047 * </ul>
048 * <p>
049 * Although this builder manages an arbitrary number of child configurations, to clients only a single configuration is
050 * visible - the one selected by the evaluation of the file name pattern. Builder reset notifications triggered by the
051 * reloading mechanism do not really take this fact into account; they are not limited to the currently selected child
052 * configuration, but occur for each of the managed configuration.
053 * </p>
054 *
055 * @param <T> the concrete type of {@code Configuration} objects created by this builder
056 * @since 2.0
057 */
058public class ReloadingMultiFileConfigurationBuilder<T extends FileBasedConfiguration> extends MultiFileConfigurationBuilder<T>
059    implements ReloadingControllerSupport {
060
061    /** The reloading controller used by this builder. */
062    private final ReloadingController reloadingController = createReloadingController();
063
064    /**
065     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} without setting initialization parameters.
066     *
067     * @param resCls the result configuration class
068     * @throws IllegalArgumentException if the result class is <strong>null</strong>
069     */
070    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls) {
071        super(resCls);
072    }
073
074    /**
075     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} and sets initialization parameters.
076     *
077     * @param resCls the result configuration class
078     * @param params a map with initialization parameters
079     * @throws IllegalArgumentException if the result class is <strong>null</strong>
080     */
081    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls, final Map<String, Object> params) {
082        super(resCls, params);
083    }
084
085    /**
086     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} and sets initialization parameters and a
087     * flag whether initialization failures should be ignored.
088     *
089     * @param resCls the result configuration class
090     * @param params a map with initialization parameters
091     * @param allowFailOnInit a flag whether initialization errors should be ignored
092     * @throws IllegalArgumentException if the result class is <strong>null</strong>
093     */
094    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls, final Map<String, Object> params, final boolean allowFailOnInit) {
095        super(resCls, params, allowFailOnInit);
096    }
097
098    /**
099     * {@inheritDoc} This implementation returns a file-based configuration builder with reloading support.
100     */
101    @Override
102    protected FileBasedConfigurationBuilder<T> createManagedBuilder(final String fileName, final Map<String, Object> params) throws ConfigurationException {
103        return new ReloadingFileBasedConfigurationBuilder<>(getResultClass(), params, isAllowFailOnInit());
104    }
105
106    /**
107     * Creates the reloading controller used by this builder. This method creates a specialized
108     * {@link CombinedReloadingController} which operates on the reloading controllers of the managed builders created so
109     * far.
110     *
111     * @return the newly created {@code ReloadingController}
112     */
113    private ReloadingController createReloadingController() {
114        final Set<ReloadingController> empty = Collections.emptySet();
115        return new CombinedReloadingController(empty) {
116            @Override
117            public Collection<ReloadingController> getSubControllers() {
118                return getManagedBuilders().values().stream().map(b -> ((ReloadingControllerSupport) b).getReloadingController()).collect(Collectors.toList());
119            }
120        };
121    }
122
123    /**
124     * {@inheritDoc} This implementation returns a special {@code ReloadingController} that delegates to the reloading
125     * controllers of the managed builders created so far.
126     */
127    @Override
128    public ReloadingController getReloadingController() {
129        return reloadingController;
130    }
131}