    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.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    /** Constant for the key in the parameters map used by this class. */
    051    private static final String PARAM_KEY = RESERVED_PARAMETER_PREFIX + MultiFileBuilderParametersImpl.class.getName();
    052
    053    /**
    054     * Obtains an instance of this class from the given map with parameters. If this map does not contain an instance,
    055     * result is <b>null</b>. This is equivalent to {@code fromParameters(params, false)}.
    056     *
    057     * @param params the map with parameters (must not be <b>null</b>)
    058     * @return an instance of this class fetched from the map or <b>null</b>
    059     * @throws NullPointerException if the map with parameters is <b>null</b>
    060     */
    061    public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params) {
    062        return fromParameters(params, false);
    063    }
    064
    065    /**
    066     * Obtains an instance of this class from the given map with parameters and creates a new object if such an instance
    067     * cannot be found. This method can be used to obtain an instance from a map which has been created using the
    068     * {@code getParameters()} method. If the map does not contain an instance under the expected key and the
    069     * {@code createIfMissing} parameter is <b>true</b>, a new instance is created. Otherwise, result is <b>null</b>.
    070     *
    071     * @param params the map with parameters (must not be <b>null</b>)
    072     * @param createIfMissing a flag whether a new instance should be created if necessary
    073     * @return an instance of this class fetched from the map or <b>null</b>
    074     * @throws NullPointerException if the map with parameters is <b>null</b>
    075     */
    076    public static MultiFileBuilderParametersImpl fromParameters(final Map<String, Object> params, final boolean createIfMissing) {
    077        MultiFileBuilderParametersImpl instance = (MultiFileBuilderParametersImpl) params.get(PARAM_KEY);
    078        if (instance == null && createIfMissing) {
    079            instance = new MultiFileBuilderParametersImpl();
    080        }
    081        return instance;
    082    }
    083
    084    /** The parameters object for managed builders. */
    085    private BuilderParameters managedBuilderParameters;
    086
    087    /** The file pattern. */
    088    private String filePattern;
    089
    090    /**
    091     * {@inheritDoc} This implementation also tries to clone the parameters object for managed builders if possible.
    092     */
    093    @Override
    094    public MultiFileBuilderParametersImpl clone() {
    095        final MultiFileBuilderParametersImpl copy = (MultiFileBuilderParametersImpl) super.clone();
    096        copy.setManagedBuilderParameters((BuilderParameters) ConfigurationUtils.cloneIfPossible(getManagedBuilderParameters()));
    097        return copy;
    098    }
    099
    100    /**
    101     * Gets the pattern for determining file names for managed configurations.
    102     *
    103     * @return the file pattern
    104     */
    105    public String getFilePattern() {
    106        return filePattern;
    107    }
    108
    109    /**
    110     * Gets the parameters object for managed configuration builders.
    111     *
    112     * @return the parameters for sub configurations
    113     */
    114    public BuilderParameters getManagedBuilderParameters() {
    115        return managedBuilderParameters;
    116    }
    117
    118    /**
    119     * {@inheritDoc} This implementation puts a reference to this object under a reserved key in the resulting parameters
    120     * map.
    121     */
    122    @Override
    123    public Map<String, Object> getParameters() {
    124        final Map<String, Object> params = super.getParameters();
    125        params.put(PARAM_KEY, this);
    126        return params;
    127    }
    128
    129    @Override
    130    public MultiFileBuilderParametersImpl setFilePattern(final String p) {
    131        filePattern = p;
    132        return this;
    133    }
    134
    135    @Override
    136    public MultiFileBuilderParametersImpl setManagedBuilderParameters(final BuilderParameters p) {
    137        managedBuilderParameters = p;
    138        return this;
    139    }
    140}