    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.Map;
    020
    021import org.apache.commons.configuration2.ConfigurationUtils;
    022import org.apache.commons.configuration2.builder.BasicBuilderParameters;
    023import org.apache.commons.configuration2.builder.BuilderParameters;
    024
    025/**
    026 * <p>
    027 * A specialized parameters object for {@link MultiFileConfigurationBuilder}.
    028 * </p>
    029 * <p>
    030 * A parameters object of this type is used by a configuration builder with manages multiple file-based configurations.
    031 * Such a builder is a bit special because it does not create a configuration on its own, but delegates to a file-based
    032 * builder for this purpose. Therefore, parameters inherited from the super class are treated differently:
    033 * </p>
    034 * <ul>
    035 * <li>The {@link org.apache.commons.configuration2.interpol.ConfigurationInterpolator ConfigurationInterpolator} is
    036 * needed by a {@code MultiFileConfigurationBuilder} to resolve the file pattern. It is expected to be set and will not
    037 * be passed to sub configurations created by the builder.</li>
    038 * <li>All other parameters are evaluated when creating sub configurations. However, it is preferred to use the
    039 * {@link #setManagedBuilderParameters(BuilderParameters)} method to define all properties of sub configurations in a
    040 * single place. If such a parameters object is set, its properties take precedence.</li>
    041 * </ul>
    042 * <p>
    043 * This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread
    044 * during configuration of a {@code ConfigurationBuilder}.
    045 * </p>
    046 *
    047 * @since 2.0
    048 */
    049public class MultiFileBuilderParametersImpl extends BasicBuilderParameters implements MultiFileBuilderProperties<MultiFileBuilderParametersImpl> {
    050
    051    /** Constant for the key in the parameters map used by this class. */
    052    private static final String PARAM_KEY = RESERVED_PARAMETER_PREFIX + MultiFileBuilderParametersImpl.class.getName();
    053
    054    /**
    055     * Obtains an instance of this class from the given map with parameters. If this map does not contain an instance,
    056     * result is <strong>null</strong>. This is equivalent to {@code fromParameters(params, false)}.
    057     *
    058     * @param params the map with parameters (must not be <strong>null</strong>)
    059     * @return an instance of this class fetched from the map or <strong>null</strong>
    060     * @throws NullPointerException if the map with parameters is <strong>null</strong>
    061     */
    062    public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params) {
    063        return fromParameters(params, false);
    064    }
    065
    066    /**
    067     * Obtains an instance of this class from the given map with parameters and creates a new object if such an instance
    068     * cannot be found. This method can be used to obtain an instance from a map which has been created using the
    069     * {@code getParameters()} method. If the map does not contain an instance under the expected key and the
    070     * {@code createIfMissing} parameter is <strong>true</strong>, a new instance is created. Otherwise, result is <strong>null</strong>.
    071     *
    072     * @param params the map with parameters (must not be <strong>null</strong>)
    073     * @param createIfMissing a flag whether a new instance should be created if necessary
    074     * @return an instance of this class fetched from the map or <strong>null</strong>
    075     * @throws NullPointerException if the map with parameters is <strong>null</strong>
    076     */
    077    public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params, final boolean createIfMissing) {
    078        MultiFileBuilderParametersImpl instance = (MultiFileBuilderParametersImpl) params.get(PARAM_KEY);
    079        if (instance == null && createIfMissing) {
    080            instance = new MultiFileBuilderParametersImpl();
    081        }
    082        return instance;
    083    }
    084
    085    /** The parameters object for managed builders. */
    086    private BuilderParameters managedBuilderParameters;
    087
    088    /** The file pattern. */
    089    private String filePattern;
    090
    091    /**
    092     * Constructs a new instance.
    093     */
    094    public MultiFileBuilderParametersImpl() {
    095        // empty
    096    }
    097
    098    /**
    099     * {@inheritDoc} This implementation also tries to clone the parameters object for managed builders if possible.
    100     */
    101    @Override
    102    public MultiFileBuilderParametersImpl clone() {
    103        final MultiFileBuilderParametersImpl copy = (MultiFileBuilderParametersImpl) super.clone();
    104        copy.setManagedBuilderParameters((BuilderParameters) ConfigurationUtils.cloneIfPossible(getManagedBuilderParameters()));
    105        return copy;
    106    }
    107
    108    /**
    109     * Gets the pattern for determining file names for managed configurations.
    110     *
    111     * @return the file pattern
    112     */
    113    public String getFilePattern() {
    114        return filePattern;
    115    }
    116
    117    /**
    118     * Gets the parameters object for managed configuration builders.
    119     *
    120     * @return the parameters for sub configurations
    121     */
    122    public BuilderParameters getManagedBuilderParameters() {
    123        return managedBuilderParameters;
    124    }
    125
    126    /**
    127     * {@inheritDoc} This implementation puts a reference to this object under a reserved key in the resulting parameters
    128     * map.
    129     */
    130    @Override
    131    public Map<String, Object> getParameters() {
    132        final Map<String, Object> params = super.getParameters();
    133        params.put(PARAM_KEY, this);
    134        return params;
    135    }
    136
    137    @Override
    138    public MultiFileBuilderParametersImpl setFilePattern(final String p) {
    139        filePattern = p;
    140        return this;
    141    }
    142
    143    @Override
    144    public MultiFileBuilderParametersImpl setManagedBuilderParameters(final BuilderParameters p) {
    145        managedBuilderParameters = p;
    146        return this;
    147    }
    148}