001/*
002 * Logback: the reliable, generic, fast and flexible logging framework.
003 * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
004 *
005 * This program and the accompanying materials are dual-licensed under
006 * either the terms of the Eclipse Public License v2.0 as published by
007 * the Eclipse Foundation
008 *
009 *   or (per the licensee's choosing)
010 *
011 * under the terms of the GNU Lesser General Public License version 2.1
012 * as published by the Free Software Foundation.
013 */
014package ch.qos.logback.classic.model.processor;
015
016import ch.qos.logback.classic.joran.ReconfigureOnChangeTask;
017import ch.qos.logback.classic.model.ConfigurationModel;
018import ch.qos.logback.core.Context;
019import ch.qos.logback.core.CoreConstants;
020import ch.qos.logback.core.joran.spi.ConfigurationWatchList;
021import ch.qos.logback.core.joran.util.ConfigurationWatchListUtil;
022import ch.qos.logback.core.model.Model;
023import ch.qos.logback.core.model.processor.ModelHandlerBase;
024import ch.qos.logback.core.model.processor.ModelHandlerException;
025import ch.qos.logback.core.model.processor.ModelInterpretationContext;
026import ch.qos.logback.core.spi.ConfigurationEvent;
027import ch.qos.logback.core.util.Duration;
028import ch.qos.logback.core.util.OptionHelper;
029
030import java.util.concurrent.ScheduledExecutorService;
031import java.util.concurrent.ScheduledFuture;
032import java.util.concurrent.TimeUnit;
033
034/**
035 * This is a subclass of {@link ConfigurationModelHandler} offering configuration reloading support.
036 *
037 * <p>This class is also called by logback-tyler.</p>
038 *
039 */
040public class ConfigurationModelHandlerFull extends ConfigurationModelHandler {
041
042    public static final String FAILED_WATCH_PREDICATE_MESSAGE_1 = "Missing watchable .xml or .properties files.";
043    public static final String FAILED_WATCH_PREDICATE_MESSAGE_2 = "Watching .xml files requires that the main configuration file is reachable as a URL";
044
045    public ConfigurationModelHandlerFull(Context context) {
046        super(context);
047    }
048
049    static public ModelHandlerBase makeInstance(Context context, ModelInterpretationContext mic) {
050        return new ConfigurationModelHandlerFull(context);
051    }
052
053    @Override
054    public void postHandle(ModelInterpretationContext mic, Model model) throws ModelHandlerException {
055        ConfigurationModel configurationModel = (ConfigurationModel) model;
056
057        // scanning is disabled at the top-level and no <propertiesConfigurator> element requested it locally
058        if (scanning != Boolean.TRUE) {
059            if (!isLocalScanRequested(mic)) {
060                return;
061            }
062            addInfo("Scan requested by <propertiesConfigurator>. Will scan for changes in watched .properties files.");
063        }
064
065        String scanPeriodStr = mic.subst(configurationModel.getScanPeriodStr());
066        scheduleReconfigureOnChangeTask(scanPeriodStr);
067
068        ConfigurationWatchList cwl = ConfigurationWatchListUtil.getConfigurationWatchList(getContext());
069        if (cwl != null) {
070            try {
071                addInfo("Main configuration file URL: " + cwl.getTopURL());
072                addInfo("FileWatchList= {" + cwl.getFileWatchListAsStr() + "}");
073                addInfo("URLWatchList= {" + cwl.getUrlWatchListAsStr() + "}");
074            } catch (NoSuchMethodError e) {
075                addWarn("It looks like the version of logback-classic is more recent than");
076                addWarn("the version of logback-core. Please align the two versions.");
077            }
078        }
079    }
080
081    private boolean isLocalScanRequested(ModelInterpretationContext mic) {
082        return mic.getObjectMap().get(PropertiesConfiguratorModelHandler.LOCAL_SCAN_REQUESTED_KEY) == Boolean.TRUE;
083    }
084
085    /**
086     * This method is called from logback-tyler version 1.0.4 and earlier.
087     * <p>
088     * This method assumes that the variables scanStr and scanPeriodStr have undergone variable substitution
089     * as applicable to their current environment
090     *
091     * @param scanPeriodStr
092     * @since 1.5.0
093     */
094    public void detachedPostProcess(String scanStr, String scanPeriodStr) {
095        if (OptionHelper.isNullOrEmptyOrAllSpaces(scanStr) || CoreConstants.FALSE_STR.equalsIgnoreCase(scanStr)) {
096            return;
097        }
098
099        scheduleReconfigureOnChangeTask(scanPeriodStr);
100    }
101
102    /**
103     * This method is called from logback-tyler version 1.0.x and later.
104     * <p>
105     * This method assumes that the variables scanPeriodStr has undergone variable substitution
106     * as applicable to their current environment
107     *
108     * @param scanPeriodStr
109     * @since 1.5.28
110     */
111    public void detachedPostProcess(String scanPeriodStr) {
112        scheduleReconfigureOnChangeTask(scanPeriodStr);
113    }
114
115
116    /**
117     * Schedules a task to monitor configuration changes and reconfigure the application when changes are detected.
118     * The task periodically scans for changes based on the given scan period and reconfigures the system if needed.
119     * This method ensures a valid configuration watch is in place before scheduling the task.
120     *
121     * @param scanPeriodStr the string value representing the scanning period, which will determine how often
122     *                      the task checks for configuration changes. The value is expected to have undergone
123     *                      necessary variable substitution for the current environment.
124     */
125    private void scheduleReconfigureOnChangeTask(String scanPeriodStr) {
126
127        boolean watchPredicateFulfilled = ConfigurationWatchListUtil.watchPredicateFulfilled(context);
128        if (!watchPredicateFulfilled) {
129            addWarn(FAILED_WATCH_PREDICATE_MESSAGE_1);
130            addWarn(FAILED_WATCH_PREDICATE_MESSAGE_2);
131            return;
132        }
133
134        ReconfigureOnChangeTask rocTask = new ReconfigureOnChangeTask();
135        rocTask.setContext(context);
136
137        addInfo("Registering a new ReconfigureOnChangeTask " + rocTask);
138
139        context.fireConfigurationEvent(ConfigurationEvent.newConfigurationChangeDetectorRegisteredEvent(rocTask));
140
141        Duration duration = getDurationOfScanPeriodAttribute(scanPeriodStr, SCAN_PERIOD_DEFAULT);
142
143        ConfigurationWatchList cwl = ConfigurationWatchListUtil.getConfigurationWatchList(context);
144
145        String fileWatchListAsStr = (cwl != null) ? cwl.getFileWatchListAsStr() : "";
146
147        addInfo("Will scan for changes in [" + fileWatchListAsStr + "] ");
148        // Given that included files are encountered at a later phase, the complete list
149        // of files to scan can only be determined when the configuration is loaded in full.
150        // However, scan can be active if mainURL is set. Otherwise, when changes are
151        // detected the top level config file cannot be accessed.
152        addInfo("Setting ReconfigureOnChangeTask scanning period to " + duration);
153
154        ScheduledExecutorService scheduledExecutorService = context.getScheduledExecutorService();
155        ScheduledFuture<?> scheduledFuture = scheduledExecutorService.scheduleAtFixedRate(rocTask, duration.getMilliseconds(), duration.getMilliseconds(),
156                TimeUnit.MILLISECONDS);
157        rocTask.setScheduledFuture(scheduledFuture);
158        context.addScheduledFuture(scheduledFuture);
159
160    }
161
162    private Duration getDurationOfScanPeriodAttribute(String scanPeriodAttrib, Duration defaultDuration) {
163        Duration duration = null;
164
165        if (!OptionHelper.isNullOrEmptyOrAllSpaces(scanPeriodAttrib)) {
166            try {
167                duration = Duration.valueOf(scanPeriodAttrib);
168            } catch (IllegalStateException | IllegalArgumentException e) {
169                addWarn("Failed to parse 'scanPeriod' attribute [" + scanPeriodAttrib + "]", e);
170                // default duration will be set below
171            }
172        }
173
174        if (duration == null) {
175            addInfo("No 'scanPeriod' specified. Defaulting to " + defaultDuration.toString());
176            duration = defaultDuration;
177        }
178        return duration;
179    }
180}