    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 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 * @since 2.0
    056 * @param <T> the concrete type of {@code Configuration} objects created by this builder
    057 */
    058public class ReloadingMultiFileConfigurationBuilder<T extends FileBasedConfiguration> extends MultiFileConfigurationBuilder<T>
    059    implements ReloadingControllerSupport {
    060    /** The reloading controller used by this builder. */
    061    private final ReloadingController reloadingController = createReloadingController();
    062
    063    /**
    064     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} and sets initialization parameters and a
    065     * flag whether initialization failures should be ignored.
    066     *
    067     * @param resCls the result configuration class
    068     * @param params a map with initialization parameters
    069     * @param allowFailOnInit a flag whether initialization errors should be ignored
    070     * @throws IllegalArgumentException if the result class is <b>null</b>
    071     */
    072    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls, final Map<String, Object> params, final boolean allowFailOnInit) {
    073        super(resCls, params, allowFailOnInit);
    074    }
    075
    076    /**
    077     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} and sets initialization parameters.
    078     *
    079     * @param resCls the result configuration class
    080     * @param params a map with initialization parameters
    081     * @throws IllegalArgumentException if the result class is <b>null</b>
    082     */
    083    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls, final Map<String, Object> params) {
    084        super(resCls, params);
    085    }
    086
    087    /**
    088     * Creates a new instance of {@code ReloadingMultiFileConfigurationBuilder} without setting initialization parameters.
    089     *
    090     * @param resCls the result configuration class
    091     * @throws IllegalArgumentException if the result class is <b>null</b>
    092     */
    093    public ReloadingMultiFileConfigurationBuilder(final Class<T> resCls) {
    094        super(resCls);
    095    }
    096
    097    /**
    098     * {@inheritDoc} This implementation returns a special {@code ReloadingController} that delegates to the reloading
    099     * controllers of the managed builders created so far.
    100     */
    101    @Override
    102    public ReloadingController getReloadingController() {
    103        return reloadingController;
    104    }
    105
    106    /**
    107     * {@inheritDoc} This implementation returns a file-based configuration builder with reloading support.
    108     */
    109    @Override
    110    protected FileBasedConfigurationBuilder<T> createManagedBuilder(final String fileName, final Map<String, Object> params) throws ConfigurationException {
    111        return new ReloadingFileBasedConfigurationBuilder<>(getResultClass(), params, isAllowFailOnInit());
    112    }
    113
    114    /**
    115     * Creates the reloading controller used by this builder. This method creates a specialized
    116     * {@link CombinedReloadingController} which operates on the reloading controllers of the managed builders created so
    117     * far.
    118     *
    119     * @return the newly created {@code ReloadingController}
    120     */
    121    private ReloadingController createReloadingController() {
    122        final Set<ReloadingController> empty = Collections.emptySet();
    123        return new CombinedReloadingController(empty) {
    124            @Override
    125            public Collection<ReloadingController> getSubControllers() {
    126                final Collection<FileBasedConfigurationBuilder<T>> builders = getManagedBuilders().values();
    127                final Collection<ReloadingController> controllers = new ArrayList<>(builders.size());
    128                for (final FileBasedConfigurationBuilder<T> b : builders) {
    129                    controllers.add(((ReloadingControllerSupport) b).getReloadingController());
    130                }
    131                return controllers;
    132            }
    133        };
    134    }
    135}