///////////////////////////////////////////////////////////////////////////////////////////////
// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
// Copyright (C) 2001-2026 the original author or authors.
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
///////////////////////////////////////////////////////////////////////////////////////////////

package com.puppycrawl.tools.checkstyle;

import java.io.IOException;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Deque;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;

import javax.xml.parsers.ParserConfigurationException;

import org.xml.sax.Attributes;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;

import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
import com.puppycrawl.tools.checkstyle.api.Configuration;
import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;

/**
 * Loads a configuration from a standard configuration XML file.
 *
 */
@SuppressWarnings("UnrecognisedJavadocTag")
public final class ConfigurationLoader {

    /**
     * Enum to specify behaviour regarding ignored modules.
     */
    public enum IgnoredModulesOptions {

        /**
         * Omit ignored modules.
         */
        OMIT,

        /**
         * Execute ignored modules.
         */
        EXECUTE,

    }

    /** The new public ID for version 1_3 of the configuration dtd. */
    public static final String DTD_PUBLIC_CS_ID_1_3 =
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN";

    /** The resource for version 1_3 of the configuration dtd. */
    public static final String DTD_CONFIGURATION_NAME_1_3 =
        "com/puppycrawl/tools/checkstyle/configuration_1_3.dtd";

    /** Format of message for sax parse exception. */
    private static final String SAX_PARSE_EXCEPTION_FORMAT = "%s - %s:%s:%s";

    /** The public ID for version 1_0 of the configuration dtd. */
    private static final String DTD_PUBLIC_ID_1_0 =
        "-//Puppy Crawl//DTD Check Configuration 1.0//EN";

    /** The new public ID for version 1_0 of the configuration dtd. */
    private static final String DTD_PUBLIC_CS_ID_1_0 =
        "-//Checkstyle//DTD Checkstyle Configuration 1.0//EN";

    /** The resource for version 1_0 of the configuration dtd. */
    private static final String DTD_CONFIGURATION_NAME_1_0 =
        "com/puppycrawl/tools/checkstyle/configuration_1_0.dtd";

    /** The public ID for version 1_1 of the configuration dtd. */
    private static final String DTD_PUBLIC_ID_1_1 =
        "-//Puppy Crawl//DTD Check Configuration 1.1//EN";

    /** The new public ID for version 1_1 of the configuration dtd. */
    private static final String DTD_PUBLIC_CS_ID_1_1 =
        "-//Checkstyle//DTD Checkstyle Configuration 1.1//EN";

    /** The resource for version 1_1 of the configuration dtd. */
    private static final String DTD_CONFIGURATION_NAME_1_1 =
        "com/puppycrawl/tools/checkstyle/configuration_1_1.dtd";

    /** The public ID for version 1_2 of the configuration dtd. */
    private static final String DTD_PUBLIC_ID_1_2 =
        "-//Puppy Crawl//DTD Check Configuration 1.2//EN";

    /** The new public ID for version 1_2 of the configuration dtd. */
    private static final String DTD_PUBLIC_CS_ID_1_2 =
        "-//Checkstyle//DTD Checkstyle Configuration 1.2//EN";

    /** The resource for version 1_2 of the configuration dtd. */
    private static final String DTD_CONFIGURATION_NAME_1_2 =
        "com/puppycrawl/tools/checkstyle/configuration_1_2.dtd";

    /** The public ID for version 1_3 of the configuration dtd. */
    private static final String DTD_PUBLIC_ID_1_3 =
        "-//Puppy Crawl//DTD Check Configuration 1.3//EN";

    /** Prefix for the exception when unable to parse resource. */
    private static final String UNABLE_TO_PARSE_EXCEPTION_PREFIX = "unable to parse"
            + " configuration stream";

    /** Dollar sign literal. */
    private static final char DOLLAR_SIGN = '$';
    /** Dollar sign string. */
    private static final String DOLLAR_SIGN_STRING = String.valueOf(DOLLAR_SIGN);

    /** Static map of DTD IDs to resource names. */
    private static final Map<String, String> ID_TO_RESOURCE_NAME_MAP = Map.ofEntries(
        Map.entry(DTD_PUBLIC_ID_1_0, DTD_CONFIGURATION_NAME_1_0),
        Map.entry(DTD_PUBLIC_ID_1_1, DTD_CONFIGURATION_NAME_1_1),
        Map.entry(DTD_PUBLIC_ID_1_2, DTD_CONFIGURATION_NAME_1_2),
        Map.entry(DTD_PUBLIC_ID_1_3, DTD_CONFIGURATION_NAME_1_3),
        Map.entry(DTD_PUBLIC_CS_ID_1_0, DTD_CONFIGURATION_NAME_1_0),
        Map.entry(DTD_PUBLIC_CS_ID_1_1, DTD_CONFIGURATION_NAME_1_1),
        Map.entry(DTD_PUBLIC_CS_ID_1_2, DTD_CONFIGURATION_NAME_1_2),
        Map.entry(DTD_PUBLIC_CS_ID_1_3, DTD_CONFIGURATION_NAME_1_3)
    );

    /** The SAX document handler. */
    private final InternalLoader saxHandler;

    /** Property resolver. **/
    private final PropertyResolver overridePropsResolver;

    /** Flags if modules with the severity 'ignore' should be omitted. */
    private final boolean omitIgnoredModules;

    /** The thread mode configuration. */
    private final ThreadModeSettings threadModeSettings;

    /**
     * Creates a new {@code ConfigurationLoader} instance.
     *
     * @param overrideProps resolver for overriding properties
     * @param omitIgnoredModules {@code true} if ignored modules should be
     *         omitted
     * @param threadModeSettings the thread mode configuration
     * @throws ParserConfigurationException if an error occurs
     * @throws SAXException if an error occurs
     */
    private ConfigurationLoader(final PropertyResolver overrideProps,
                                final boolean omitIgnoredModules,
                                final ThreadModeSettings threadModeSettings)
            throws ParserConfigurationException, SAXException {
        saxHandler = new InternalLoader();
        overridePropsResolver = overrideProps;
        this.omitIgnoredModules = omitIgnoredModules;
        this.threadModeSettings = threadModeSettings;
    }

    /**
     * Parses the specified input source loading the configuration information.
     * The stream wrapped inside the source, if any, is NOT
     * explicitly closed after parsing, it is the responsibility of
     * the caller to close the stream.
     *
     * @param source the source that contains the configuration data
     * @return the check configurations
     * @throws IOException if an error occurs
     * @throws SAXException if an error occurs
     */
    private Configuration parseInputSource(InputSource source)
            throws IOException, SAXException {
        saxHandler.parseInputSource(source);
        return saxHandler.configuration;
    }

    /**
     * Returns the module configurations in a specified file.
     *
     * @param config location of config file, can be either a URL or a filename
     * @param overridePropsResolver overriding properties
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     */
    public static Configuration loadConfiguration(String config,
            PropertyResolver overridePropsResolver) throws CheckstyleException {
        return loadConfiguration(config, overridePropsResolver, IgnoredModulesOptions.EXECUTE);
    }

    /**
     * Returns the module configurations in a specified file.
     *
     * @param config location of config file, can be either a URL or a filename
     * @param overridePropsResolver overriding properties
     * @param threadModeSettings the thread mode configuration
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     */
    public static Configuration loadConfiguration(String config,
            PropertyResolver overridePropsResolver, ThreadModeSettings threadModeSettings)
            throws CheckstyleException {
        return loadConfiguration(config, overridePropsResolver,
                IgnoredModulesOptions.EXECUTE, threadModeSettings);
    }

    /**
     * Returns the module configurations in a specified file.
     *
     * @param config location of config file, can be either a URL or a filename
     * @param overridePropsResolver overriding properties
     * @param ignoredModulesOptions {@code OMIT} if modules with severity
     *            'ignore' should be omitted, {@code EXECUTE} otherwise
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     */
    public static Configuration loadConfiguration(String config,
                                                  PropertyResolver overridePropsResolver,
                                                  IgnoredModulesOptions ignoredModulesOptions)
            throws CheckstyleException {
        return loadConfiguration(config, overridePropsResolver, ignoredModulesOptions,
                ThreadModeSettings.SINGLE_THREAD_MODE_INSTANCE);
    }

    /**
     * Returns the module configurations in a specified file.
     *
     * @param config location of config file, can be either a URL or a filename
     * @param overridePropsResolver overriding properties
     * @param ignoredModulesOptions {@code OMIT} if modules with severity
     *            'ignore' should be omitted, {@code EXECUTE} otherwise
     * @param threadModeSettings the thread mode configuration
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     */
    public static Configuration loadConfiguration(String config,
                                                  PropertyResolver overridePropsResolver,
                                                  IgnoredModulesOptions ignoredModulesOptions,
                                                  ThreadModeSettings threadModeSettings)
            throws CheckstyleException {
        return loadConfiguration(CommonUtil.sourceFromFilename(config), overridePropsResolver,
                ignoredModulesOptions, threadModeSettings);
    }

    /**
     * Returns the module configurations from a specified input source.
     * Note that if the source does wrap an open byte or character
     * stream, clients are required to close that stream by themselves
     *
     * @param configSource the input stream to the Checkstyle configuration
     * @param overridePropsResolver overriding properties
     * @param ignoredModulesOptions {@code OMIT} if modules with severity
     *            'ignore' should be omitted, {@code EXECUTE} otherwise
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     */
    public static Configuration loadConfiguration(InputSource configSource,
                                                  PropertyResolver overridePropsResolver,
                                                  IgnoredModulesOptions ignoredModulesOptions)
            throws CheckstyleException {
        return loadConfiguration(configSource, overridePropsResolver,
                ignoredModulesOptions, ThreadModeSettings.SINGLE_THREAD_MODE_INSTANCE);
    }

    /**
     * Returns the module configurations from a specified input source.
     * Note that if the source does wrap an open byte or character
     * stream, clients are required to close that stream by themselves
     *
     * @param configSource the input stream to the Checkstyle configuration
     * @param overridePropsResolver overriding properties
     * @param ignoredModulesOptions {@code OMIT} if modules with severity
     *            'ignore' should be omitted, {@code EXECUTE} otherwise
     * @param threadModeSettings the thread mode configuration
     * @return the check configurations
     * @throws CheckstyleException if an error occurs
     * @noinspection WeakerAccess
     * @noinspectionreason WeakerAccess - we avoid 'protected' when possible
     */
    public static Configuration loadConfiguration(InputSource configSource,
                                                  PropertyResolver overridePropsResolver,
                                                  IgnoredModulesOptions ignoredModulesOptions,
                                                  ThreadModeSettings threadModeSettings)
            throws CheckstyleException {
        try {
            final boolean omitIgnoreModules = ignoredModulesOptions == IgnoredModulesOptions.OMIT;
            final ConfigurationLoader loader =
                    new ConfigurationLoader(overridePropsResolver,
                            omitIgnoreModules, threadModeSettings);
            return loader.parseInputSource(configSource);
        }
        catch (final SAXParseException exc) {
            final String message = String.format(Locale.ROOT, SAX_PARSE_EXCEPTION_FORMAT,
                    UNABLE_TO_PARSE_EXCEPTION_PREFIX,
                    exc.getMessage(), exc.getLineNumber(), exc.getColumnNumber());
            throw new CheckstyleException(message, exc);
        }
        catch (final ParserConfigurationException | IOException | SAXException exc) {
            throw new CheckstyleException(UNABLE_TO_PARSE_EXCEPTION_PREFIX, exc);
        }
    }

    /**
     * Implements the SAX document handler interfaces, so they do not
     * appear in the public API of the ConfigurationLoader.
     */
    private final class InternalLoader
        extends XmlLoader {

        /** Module elements. */
        private static final String MODULE = "module";
        /** Name attribute. */
        private static final String NAME = "name";
        /** Property element. */
        private static final String PROPERTY = "property";
        /** Value attribute. */
        private static final String VALUE = "value";
        /** Default attribute. */
        private static final String DEFAULT = "default";
        /** Name of the severity property. */
        private static final String SEVERITY = "severity";
        /** Name of the message element. */
        private static final String MESSAGE = "message";
        /** Name of the message element. */
        private static final String METADATA = "metadata";
        /** Name of the key attribute. */
        private static final String KEY = "key";

        /** The loaded configurations. **/
        private final Deque<DefaultConfiguration> configStack = new ArrayDeque<>();

        /** The Configuration that is being built. */
        private Configuration configuration;

        /**
         * Creates a new InternalLoader.
         *
         * @throws SAXException if an error occurs
         * @throws ParserConfigurationException if an error occurs
         */
        private InternalLoader()
                throws SAXException, ParserConfigurationException {
            super(ID_TO_RESOURCE_NAME_MAP);
        }

        /**
         * Replaces {@code ${xxx}} style constructions in the given value
         * with the string value of the corresponding data types.
         *
         * <p>Code copied from
         * <a href="https://github.com/apache/ant/blob/master/src/main/org/apache/tools/ant/ProjectHelper.java">
         * ant
         * </a>
         *
         * @param value The string to be scanned for property references. Must
         *              not be {@code null}.
         * @param defaultValue default to use if one of the properties in value
         *              cannot be resolved from props.
         *
         * @return the original string with the properties replaced.
         * @throws CheckstyleException if the string contains an opening
         *                           {@code ${} without a closing
         *                           {@code }}
         */
        private String replaceProperties(
                String value, String defaultValue)
                throws CheckstyleException {

            final List<String> fragments = new ArrayList<>();
            final List<String> propertyRefs = new ArrayList<>();
            parsePropertyString(value, fragments, propertyRefs);

            final StringBuilder sb = new StringBuilder(256);
            final Iterator<String> fragmentsIterator = fragments.iterator();
            final Iterator<String> propertyRefsIterator = propertyRefs.iterator();
            while (fragmentsIterator.hasNext()) {
                String fragment = fragmentsIterator.next();
                if (fragment == null) {
                    final String propertyName = propertyRefsIterator.next();
                    fragment = overridePropsResolver.resolve(propertyName);
                    if (fragment == null) {
                        if (defaultValue != null) {
                            sb.replace(0, sb.length(), defaultValue);
                            break;
                        }
                        throw new CheckstyleException(
                            "Property ${" + propertyName + "} has not been set");
                    }
                }
                sb.append(fragment);
            }

            return sb.toString();
        }

        /**
         * Parses a string containing {@code ${xxx}} style property
         * references into two collections. The first one is a collection
         * of text fragments, while the other is a set of string property names.
         * {@code null} entries in the first collection indicate a property
         * reference from the second collection.
         *
         * <p>Code copied from
         * <a href="https://github.com/apache/ant/blob/master/src/main/org/apache/tools/ant/ProjectHelper.java">
         * ant
         * </a>
         *
         * @param value     Text to parse. Must not be {@code null}.
         * @param fragments Collection to add text fragments to.
         *                  Must not be {@code null}.
         * @param propertyRefs Collection to add property names to.
         *                     Must not be {@code null}.
         *
         * @throws CheckstyleException if the string contains an opening
         *                           {@code ${} without a closing
         *                           {@code }}
         */
        private static void parsePropertyString(String value,
                                               Collection<String> fragments,
                                               Collection<String> propertyRefs)
                throws CheckstyleException {
            int prev = 0;
            // search for the next instance of $ from the 'prev' position
            int pos = value.indexOf(DOLLAR_SIGN, prev);
            while (pos >= 0) {
                // if there was any text before this, add it as a fragment
                if (pos > 0) {
                    fragments.add(value.substring(prev, pos));
                }
                // if we are at the end of the string, we tack on a $
                // then move past it
                if (pos == value.length() - 1) {
                    fragments.add(DOLLAR_SIGN_STRING);
                    prev = pos + 1;
                }
                else if (value.charAt(pos + 1) == '{') {
                    // property found, extract its name or bail on a typo
                    final int endName = value.indexOf('}', pos);
                    if (endName == -1) {
                        throw new CheckstyleException("Syntax error in property: "
                                                        + value);
                    }
                    final String propertyName = value.substring(pos + 2, endName);
                    fragments.add(null);
                    propertyRefs.add(propertyName);
                    prev = endName + 1;
                }
                else {
                    if (value.charAt(pos + 1) == DOLLAR_SIGN) {
                        // backwards compatibility two $ map to one mode
                        fragments.add(DOLLAR_SIGN_STRING);
                    }
                    else {
                        // new behaviour: $X maps to $X for all values of X!='$'
                        fragments.add(value.substring(pos, pos + 2));
                    }
                    prev = pos + 2;
                }

                // search for the next instance of $ from the 'prev' position
                pos = value.indexOf(DOLLAR_SIGN, prev);
            }
            // no more $ signs found
            // if there is any tail to the file, append it
            if (prev < value.length()) {
                fragments.add(value.substring(prev));
            }
        }

        @Override
        public void startElement(String uri,
                                 String localName,
                                 String qName,
                                 Attributes attributes)
                throws SAXException {
            if (MODULE.equals(qName)) {
                // create configuration
                final String originalName = attributes.getValue(NAME);
                final String name = threadModeSettings.resolveName(originalName);
                final DefaultConfiguration conf =
                    new DefaultConfiguration(name, threadModeSettings);

                if (configStack.isEmpty()) {
                    // save top config
                    configuration = conf;
                }
                else {
                    // add configuration to it's parent
                    final DefaultConfiguration top =
                        configStack.peek();
                    top.addChild(conf);
                }

                configStack.push(conf);
            }
            else if (PROPERTY.equals(qName)) {
                // extract value and name
                final String attributesValue = attributes.getValue(VALUE);

                final String value;
                try {
                    value = replaceProperties(attributesValue, attributes.getValue(DEFAULT));
                }
                catch (final CheckstyleException exc) {
                    // -@cs[IllegalInstantiation] SAXException is in the overridden
                    // method signature
                    throw new SAXException(exc);
                }

                final String name = attributes.getValue(NAME);

                // add to attributes of configuration
                final DefaultConfiguration top =
                    configStack.peek();
                top.addProperty(name, value);
            }
            else if (MESSAGE.equals(qName)) {
                // extract key and value
                final String key = attributes.getValue(KEY);
                final String value = attributes.getValue(VALUE);

                // add to messages of configuration
                final DefaultConfiguration top = configStack.peek();
                top.addMessage(key, value);
            }
            else {
                if (!METADATA.equals(qName)) {
                    throw new IllegalStateException("Unknown name:" + qName + ".");
                }
            }
        }

        @Override
        public void endElement(String uri,
                               String localName,
                               String qName) throws SAXException {
            if (MODULE.equals(qName)) {
                final Configuration recentModule =
                    configStack.pop();

                // get severity attribute if it exists
                Optional<SeverityLevel> level = Optional.empty();
                if (containsAttribute(recentModule, SEVERITY)) {
                    try {
                        final String severity = recentModule.getProperty(SEVERITY);
                        level = Optional.of(SeverityLevel.getInstance(severity));
                    }
                    catch (final CheckstyleException exc) {
                        // -@cs[IllegalInstantiation] SAXException is in the overridden
                        // method signature
                        throw new SAXException(
                                "Problem during accessing '" + SEVERITY + "' attribute for "
                                        + recentModule.getName(), exc);
                    }
                }

                // omit this module if these should be omitted and the module
                // has the severity 'ignore'
                final boolean omitModule = omitIgnoredModules
                    && level.isPresent() && level.get() == SeverityLevel.IGNORE;

                if (omitModule && !configStack.isEmpty()) {
                    final DefaultConfiguration parentModule = configStack.peek();
                    parentModule.removeChild(recentModule);
                }
            }
        }

        /**
         * Util method to recheck attribute in module.
         *
         * @param module module to check
         * @param attributeName name of attribute in module to find
         * @return true if attribute is present in module
         */
        private static boolean containsAttribute(Configuration module, String attributeName) {
            final String[] names = module.getPropertyNames();
            final Optional<String> result = Arrays.stream(names)
                    .filter(name -> name.equals(attributeName)).findFirst();
            return result.isPresent();
        }

    }

}