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