    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 *     http://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.ArrayList;
    020import java.util.Collection;
    021import java.util.Collections;
    022import java.util.Map;
    023import java.util.Set;
    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
    036 * support for reloading.
    037 * </p>
    038 * <p>
    039 * This class - as its super class - allows operating on multiple configuration
    040 * files whose file names are determined using a file name pattern and a
    041 * {@code ConfigurationInterpolator} object. It provides the following
    042 * additional features:
    043 * </p>
    044 * <ul>
    045 * <li>Configuration builder for managed configurations have reloading support.
    046 * So reloading is possible for all configuration sources loaded by this builder
    047 * instance.</li>
    048 * <li>A {@link ReloadingController} is provided which can be used to trigger
    049 * reload checks on all managed configurations.</li>
    050 * </ul>
    051 * <p>
    052 * Although this builder manages an arbitrary number of child configurations, to
    053 * clients only a single configuration is visible - the one selected by the
    054 * evaluation of the file name pattern. Builder reset notifications triggered by
    055 * the reloading mechanism do not really take this fact into account; they are
    056 * not limited to the currently selected child configuration, but occur for each
    057 * of the managed configuration.
    058 * </p>
    059 *
    060 * @version $Id: ReloadingMultiFileConfigurationBuilder.java 1842194 2018-09-27 22:24:23Z ggregory $
    061 * @since 2.0
    062 * @param <T> the concrete type of {@code Configuration} objects created by this
    063 *        builder
    064 */
    065public class ReloadingMultiFileConfigurationBuilder<T extends FileBasedConfiguration>
    066        extends MultiFileConfigurationBuilder<T> implements
    067        ReloadingControllerSupport
    068{
    069    /** The reloading controller used by this builder. */
    070    private final ReloadingController reloadingController =
    071            createReloadingController();
    072
    073    /**
    074     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder}
    075     * and sets initialization parameters and a flag whether initialization
    076     * failures should be ignored.
    077     *
    078     * @param resCls the result configuration class
    079     * @param params a map with initialization parameters
    080     * @param allowFailOnInit a flag whether initialization errors should be
    081     *        ignored
    082     * @throws IllegalArgumentException if the result class is <b>null</b>
    083     */
    084    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls,
    085            final Map<String, Object> params, final boolean allowFailOnInit)
    086    {
    087        super(resCls, params, allowFailOnInit);
    088    }
    089
    090    /**
    091     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder}
    092     * and sets initialization parameters.
    093     *
    094     * @param resCls the result configuration class
    095     * @param params a map with initialization parameters
    096     * @throws IllegalArgumentException if the result class is <b>null</b>
    097     */
    098    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls,
    099            final Map<String, Object> params)
    100    {
    101        super(resCls, params);
    102    }
    103
    104    /**
    105     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder}
    106     * without setting initialization parameters.
    107     *
    108     * @param resCls the result configuration class
    109     * @throws IllegalArgumentException if the result class is <b>null</b>
    110     */
    111    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls)
    112    {
    113        super(resCls);
    114    }
    115
    116    /**
    117     * {@inheritDoc} This implementation returns a special
    118     * {@code ReloadingController} that delegates to the reloading controllers
    119     * of the managed builders created so far.
    120     */
    121    @Override
    122    public ReloadingController getReloadingController()
    123    {
    124        return reloadingController;
    125    }
    126
    127    /**
    128     * {@inheritDoc} This implementation returns a file-based configuration
    129     * builder with reloading support.
    130     */
    131    @Override
    132    protected FileBasedConfigurationBuilder<T> createManagedBuilder(
    133            final String fileName, final Map<String, Object> params)
    134            throws ConfigurationException
    135    {
    136        return new ReloadingFileBasedConfigurationBuilder<>(getResultClass(),
    137                params, isAllowFailOnInit());
    138    }
    139
    140    /**
    141     * Creates the reloading controller used by this builder. This method
    142     * creates a specialized {@link CombinedReloadingController} which operates
    143     * on the reloading controllers of the managed builders created so far.
    144     *
    145     * @return the newly created {@code ReloadingController}
    146     */
    147    private ReloadingController createReloadingController()
    148    {
    149        final Set<ReloadingController> empty = Collections.emptySet();
    150        return new CombinedReloadingController(empty)
    151        {
    152            @Override
    153            public Collection<ReloadingController> getSubControllers()
    154            {
    155                final Collection<FileBasedConfigurationBuilder<T>> builders =
    156                        getManagedBuilders().values();
    157                final Collection<ReloadingController> controllers =
    158                        new ArrayList<>(builders.size());
    159                for (final FileBasedConfigurationBuilder<T> b : builders)
    160                {
    161                    controllers.add(((ReloadingControllerSupport) b)
    162                            .getReloadingController());
    163                }
    164                return controllers;
    165            }
    166        };
    167    }
    168}