/*
 * 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:
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:
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; } }