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