/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration2.builder.combined;
import java.util.Map;
import org.apache.commons.configuration2.ConfigurationUtils;
import org.apache.commons.configuration2.builder.BasicBuilderParameters;
import org.apache.commons.configuration2.builder.BuilderParameters;
A specialized parameters object for MultiFileConfigurationBuilder
.
A parameters object of this type is used by a configuration builder with
manages multiple file-based configurations. Such a builder is a bit special
because it does not create a configuration on its own, but delegates to a
file-based builder for this purpose. Therefore, parameters inherited from the
super class are treated differently:
- The
ConfigurationInterpolator
is needed by a MultiFileConfigurationBuilder
to resolve the file pattern. It is expected to be set and will not be passed to sub configurations created by the builder.
- All other parameters are evaluated when creating sub configurations. However, it is preferred to use the
setManagedBuilderParameters(BuilderParameters)
method to define all properties of sub configurations in a single place. If such a parameters object is set, its properties take precedence.
This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread during configuration of a ConfigurationBuilder
.
Since: 2.0
/**
* <p>
* A specialized parameters object for {@link MultiFileConfigurationBuilder}.
* </p>
* <p>
* A parameters object of this type is used by a configuration builder with
* manages multiple file-based configurations. Such a builder is a bit special
* because it does not create a configuration on its own, but delegates to a
* file-based builder for this purpose. Therefore, parameters inherited from the
* super class are treated differently:
* </p>
* <ul>
* <li>The {@link org.apache.commons.configuration2.interpol.ConfigurationInterpolator
* ConfigurationInterpolator} is needed by a
* {@code MultiFileConfigurationBuilder} to resolve the file pattern. It is
* expected to be set and will not be passed to sub configurations created by
* the builder.</li>
* <li>All other parameters are evaluated when creating sub configurations.
* However, it is preferred to use the
* {@link #setManagedBuilderParameters(BuilderParameters)} method to define all
* properties of sub configurations in a single place. If such a parameters
* object is set, its properties take precedence.</li>
* </ul>
* <p>
* This class is not thread-safe. It is intended that an instance is constructed
* and initialized by a single thread during configuration of a
* {@code ConfigurationBuilder}.
* </p>
*
* @since 2.0
*/
public class MultiFileBuilderParametersImpl extends BasicBuilderParameters
implements MultiFileBuilderProperties<MultiFileBuilderParametersImpl>
{
Constant for the key in the parameters map used by this class. /** Constant for the key in the parameters map used by this class. */
private static final String PARAM_KEY = RESERVED_PARAMETER_PREFIX
+ MultiFileBuilderParametersImpl.class.getName();
The parameters object for managed builders. /** The parameters object for managed builders. */
private BuilderParameters managedBuilderParameters;
The file pattern. /** The file pattern. */
private String filePattern;
Obtains an instance of this class from the given map with parameters. If
this map does not contain an instance, result is null. This is equivalent to fromParameters(params, false)
. Params: - params – the map with parameters (must not be null)
Throws: - NullPointerException – if the map with parameters is null
Returns: an instance of this class fetched from the map or null
/**
* Obtains an instance of this class from the given map with parameters. If
* this map does not contain an instance, result is <b>null</b>. This is
* equivalent to {@code fromParameters(params, false)}.
*
* @param params the map with parameters (must not be <b>null</b>)
* @return an instance of this class fetched from the map or <b>null</b>
* @throws NullPointerException if the map with parameters is <b>null</b>
*/
public static MultiFileBuilderParametersImpl fromParameters(
final Map<String, Object> params)
{
return fromParameters(params, false);
}
Obtains an instance of this class from the given map with parameters and creates a new object if such an instance cannot be found. This method can be used to obtain an instance from a map which has been created using the getParameters()
method. If the map does not contain an instance under the expected key and the createIfMissing
parameter is true, a new instance is created. Otherwise, result is null.
Params: - params – the map with parameters (must not be null)
- createIfMissing – a flag whether a new instance should be created if
necessary
Throws: - NullPointerException – if the map with parameters is null
Returns: an instance of this class fetched from the map or null
/**
* Obtains an instance of this class from the given map with parameters and
* creates a new object if such an instance cannot be found. This method can
* be used to obtain an instance from a map which has been created using the
* {@code getParameters()} method. If the map does not contain an instance
* under the expected key and the {@code createIfMissing} parameter is
* <b>true</b>, a new instance is created. Otherwise, result is <b>null</b>.
*
* @param params the map with parameters (must not be <b>null</b>)
* @param createIfMissing a flag whether a new instance should be created if
* necessary
* @return an instance of this class fetched from the map or <b>null</b>
* @throws NullPointerException if the map with parameters is <b>null</b>
*/
public static MultiFileBuilderParametersImpl fromParameters(
final Map<String, Object> params, final boolean createIfMissing)
{
MultiFileBuilderParametersImpl instance =
(MultiFileBuilderParametersImpl) params.get(PARAM_KEY);
if (instance == null && createIfMissing)
{
instance = new MultiFileBuilderParametersImpl();
}
return instance;
}
Returns the pattern for determining file names for managed
configurations.
Returns: the file pattern
/**
* Returns the pattern for determining file names for managed
* configurations.
*
* @return the file pattern
*/
public String getFilePattern()
{
return filePattern;
}
@Override
public MultiFileBuilderParametersImpl setFilePattern(final String p)
{
filePattern = p;
return this;
}
Returns the parameters object for managed configuration builders.
Returns: the parameters for sub configurations
/**
* Returns the parameters object for managed configuration builders.
*
* @return the parameters for sub configurations
*/
public BuilderParameters getManagedBuilderParameters()
{
return managedBuilderParameters;
}
@Override
public MultiFileBuilderParametersImpl setManagedBuilderParameters(
final BuilderParameters p)
{
managedBuilderParameters = p;
return this;
}
{@inheritDoc} This implementation puts a reference to this object under a
reserved key in the resulting parameters map.
/**
* {@inheritDoc} This implementation puts a reference to this object under a
* reserved key in the resulting parameters map.
*/
@Override
public Map<String, Object> getParameters()
{
final Map<String, Object> params = super.getParameters();
params.put(PARAM_KEY, this);
return params;
}
{@inheritDoc} This implementation also tries to clone the parameters
object for managed builders if possible.
/**
* {@inheritDoc} This implementation also tries to clone the parameters
* object for managed builders if possible.
*/
@Override
public MultiFileBuilderParametersImpl clone()
{
final MultiFileBuilderParametersImpl copy =
(MultiFileBuilderParametersImpl) super.clone();
copy.setManagedBuilderParameters((BuilderParameters) ConfigurationUtils
.cloneIfPossible(getManagedBuilderParameters()));
return copy;
}
}