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.Collection;
020
021import org.apache.commons.configuration2.builder.BuilderParameters;
022import org.apache.commons.configuration2.builder.FileBasedBuilderParametersImpl;
023import org.apache.commons.configuration2.ex.ConfigurationException;
024
025/**
026 * <p>
027 * A specialized implementation of {@link ConfigurationBuilderProvider} which
028 * determines the name of the result configuration class based on the extension
029 * of the file to load.
030 * </p>
031 * <p>
032 * This class works analogously to its base class {@link BaseConfigurationBuilderProvider};
033 * especially, the resulting builder is created based on reflection. It extends
034 * the super class's functionality by a specific mechanism for determining the
035 * resulting configuration class: At construction time two configuration class
036 * names and a file extension are passed in. If a file name is provided in the
037 * builder's initialization parameters and this file name has the specified
038 * extension, then the first configuration class name is used; otherwise the
039 * default configuration class name is selected.
040 * </p>
041 * <p>
042 * There are some tags for {@code CombinedConfigurationProvider} which can
043 * produce different results depending on the configuration files they have to
044 * load. This class can be used to implement this feature in a generic way.
045 * </p>
046 *
047 * @since 2.0
048 */
049public class FileExtensionConfigurationBuilderProvider extends
050        BaseConfigurationBuilderProvider
051{
052    /** Constant for the file extension separator. */
053    private static final char EXT_SEPARATOR = '.';
054
055    /** The matching configuration class. */
056    private final String matchingConfigurationClass;
057
058    /** The file extension. */
059    private final String extension;
060
061    /**
062     * Creates a new instance of
063     * {@code FileExtensionConfigurationBuilderProvider}.
064     *
065     * @param bldrCls the name of the builder class
066     * @param reloadBldrCls the name of a builder class to be used if reloading
067     *        support is required (<b>null</b> if reloading is not supported)
068     * @param matchingConfigCls the name of the configuration class to be used
069     *        if the provided file extension matches (must not be <b>null</b>)
070     * @param defConfigClass the name of the configuration class to be used if
071     *        the provided file extension does not match (must not be
072     *        <b>null</b>)
073     * @param ext the file extension to select the configuration class (must not
074     *        be <b>null</b>)
075     * @param paramCls a collection with the names of parameters classes; an
076     *        instance of a parameters object with basic properties is created
077     *        automatically and does not need to be contained in this list; the
078     *        collection can be <b>null</b> if no additional parameter objects
079     *        are needed
080     * @throws IllegalArgumentException if a required parameter is missing
081     */
082    public FileExtensionConfigurationBuilderProvider(final String bldrCls,
083            final String reloadBldrCls, final String matchingConfigCls,
084            final String defConfigClass, final String ext, final Collection<String> paramCls)
085    {
086        super(bldrCls, reloadBldrCls, defConfigClass, paramCls);
087        if (matchingConfigCls == null)
088        {
089            throw new IllegalArgumentException(
090                    "Matching configuration class must not be null!");
091        }
092        if (ext == null)
093        {
094            throw new IllegalArgumentException(
095                    "File extension must not be null!");
096        }
097
098        matchingConfigurationClass = matchingConfigCls;
099        extension = ext;
100    }
101
102    /**
103     * Returns the name of the matching configuration class. This class is used
104     * if the file extension matches the extension of this provider.
105     *
106     * @return the matching configuration class
107     */
108    public String getMatchingConfigurationClass()
109    {
110        return matchingConfigurationClass;
111    }
112
113    /**
114     * Returns the file extension of this provider.
115     *
116     * @return the file extension to match
117     */
118    public String getExtension()
119    {
120        return extension;
121    }
122
123    /**
124     * {@inheritDoc} This implementation tries to find a
125     * {@link FileBasedBuilderParametersImpl} object in the parameter objects. If
126     * one is found, the extension of the file name is obtained and compared
127     * against the stored file extension. In case of a match, the matching
128     * configuration class is selected, otherwise the default one.
129     */
130    @Override
131    protected String determineConfigurationClass(final ConfigurationDeclaration decl,
132            final Collection<BuilderParameters> params) throws ConfigurationException
133    {
134        final String currentExt = extractExtension(fetchCurrentFileName(params));
135        return getExtension().equalsIgnoreCase(currentExt) ? getMatchingConfigurationClass()
136                : getConfigurationClass();
137    }
138
139    /**
140     * Tries to obtain the current file name from the given list of parameter
141     * objects.
142     *
143     * @param params the parameter objects
144     * @return the file name or <b>null</b> if unspecified
145     */
146    private static String fetchCurrentFileName(
147            final Collection<BuilderParameters> params)
148    {
149        for (final BuilderParameters p : params)
150        {
151            if (p instanceof FileBasedBuilderParametersImpl)
152            {
153                final FileBasedBuilderParametersImpl fp = (FileBasedBuilderParametersImpl) p;
154                return fp.getFileHandler().getFileName();
155            }
156        }
157        return null;
158    }
159
160    /**
161     * Extracts the extension from the given file name. The name can be
162     * <b>null</b>.
163     *
164     * @param fileName the file name
165     * @return the extension (<b>null</b> if there is none)
166     */
167    private static String extractExtension(final String fileName)
168    {
169        if (fileName == null)
170        {
171            return null;
172        }
173
174        final int pos = fileName.lastIndexOf(EXT_SEPARATOR);
175        return pos < 0 ? null : fileName.substring(pos + 1);
176    }
177}