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