/src/logging-log4cxx/src/main/include/log4cxx/defaultconfigurator.h

Source
/*
 * 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.
 */

#ifndef _LOG4CXX_DEFAULT_CONFIGURATOR_H
#define _LOG4CXX_DEFAULT_CONFIGURATOR_H

#include <log4cxx/spi/configurator.h>
#include <log4cxx/spi/loggerrepository.h>
#include <tuple>

namespace LOG4CXX_NS
{

/**
 *   Configures the repository from environmental settings and files.
*
*/
class LOG4CXX_EXPORT DefaultConfigurator
{
  private:
    DefaultConfigurator() {}

  public:
    /**
    Configure \c repository.

    If the configuration file name has not been provided by a call to setConfigurationFileName(),
    the environment variable "LOG4CXX_CONFIGURATION" or "log4j.configuration" value is used,
    with ${varname} instances using either a system environment variable value (if found)
    otherwise using the helpers::Properties object
    provided by spi::Configurator::properties.

    \usage
    ~~~
    setenv LOG4CXX_CONFIGURATION="${PROGRAM_FILE_PATH.PARENT_PATH}/${PROGRAM_FILE_PATH.STEM}.xml"
    ~~~

    Unless a custom configurator is specified using the
    "LOG4CXX_CONFIGURATOR_CLASS" or "log4j.configuratorClass"
    environment variable, the PropertyConfigurator will be used to
    configure log4cxx unless the file name ends with the ".xml"
    extension, in which case the DOMConfigurator will be used. If a
    custom configurator is specified, the environment variable should
    contain a fully qualified class name of a class that implements the
    Configurator interface.

    If the configuration file name is not found using any of the previous approaches,
    the current directory is examined for a file with extension ".xml" or ".properties"
    with a base name "log4cxx" or "log4j".

    If a positive number has been provided by a call to setConfigurationWatchSeconds()
    or the environment variables "LOG4CXX_CONFIGURATION_WATCH_SECONDS" contains a positive number
    a background thread is started that will periodically check for a change to the configuration file
    and apply any configuration changes found.

    Call the spi::LoggerRepository::isConfigured \c repository member function
    to determine whether a configuration file was found.
    */
    static void configure(spi::LoggerRepositoryPtr repository);

    /**
    Attempt configuration by calling configure() passing the default repository.

    See configure() for how the configuration file name is determined.

    @return a success indicator.
    */
    static spi::ConfigurationStatus tryConfigure();

    /**
    Make \c path the configuration file used by configure().

    Any ${varname} instances in the \c path value are expanded
    using either a system environment variable value (if found)
    otherwise using the map provided by spi::Configurator::properties.

    \usage
    ~~~{.cpp}
    DefaultConfigurator::setConfigurationFileName(LOG4CXX_STR("${PROGRAM_FILE_PATH.PARENT_PATH}/${PROGRAM_FILE_PATH.STEM}.xml"))
    ~~~

    */
    static void setConfigurationFileName(const LogString& path);

    /**
    Make \c seconds the time a background thread will delay before checking
    for a change to the configuration file used by configure().

    \usage
    ~~~{.cpp}
    DefaultConfigurator::setConfigurationWatchSeconds(1);
    ~~~
    */
    static void setConfigurationWatchSeconds(int seconds);

    /**
     * Call configure() passing the default repository
     * after calling setConfigurationFileName() with a path composed of
     * an entry in \c directories and an entry in \c filenames
     * when the combination identifies an existing file.
     *
     \usage
     ~~~{.cpp}
     std::vector<LogString> directories
         { LOG4CXX_STR(".")
         , LOG4CXX_STR("${PROGRAM_FILE_PATH.PARENT_PATH}")
         };
     std::vector<LogString> filenames
         { LOG4CXX_STR("${PROGRAM_FILE_PATH.STEM}.xml")
         , LOG4CXX_STR("${PROGRAM_FILE_PATH.STEM}.properties")
         , LOG4CXX_STR("log4cxx.xml")
         };
     DefaultConfigurator::configureFromFile(directories, filenames);
     ~~~
     *
     * Using the above example and an executable file named "myapp"
     * installed in the  directory "/opt/com.foo/bin",
     * locations are checked in the following order:
     * -# "./myapp.xml"
     * -# "./myapp.properties"
     * -# "./log4cxx.xml"
     * -# "/opt/com.foo/bin/myapp.xml"
     * -# "/opt/com.foo/bin/myapp.properties"
     * -# "/opt/com.foo/bin/log4cxx.xml"
     *
     * If a file exists but it is not able to be used to configure Log4cxx,
     * the next file in the combinatorial set will be tried until
     * a valid configuration file is found or
     * all values in the combinatorial set have been tried.
     *
     * @param directories The directories to look in.
     * @param filenames The names of the files to look for
     * @return a success indicator and the configuration file path that was used (if found).
     */
    static std::tuple<spi::ConfigurationStatus,LogString> configureFromFile
      ( const std::vector<LogString>& directories
      , const std::vector<LogString>& filenames
      );

  private:
    static const LogString getConfigurationFileName();
    static const LogString getConfiguratorClass();
    static int getConfigurationWatchDelay();

};   // class DefaultConfigurator
}  // namespace log4cxx

#endif //_LOG4CXX_DEFAULT_CONFIGURATOR_H

Line	Count	Source
1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17
18		#ifndef _LOG4CXX_DEFAULT_CONFIGURATOR_H
19		#define _LOG4CXX_DEFAULT_CONFIGURATOR_H
20
21		#include <log4cxx/spi/configurator.h>
22		#include <log4cxx/spi/loggerrepository.h>
23		#include <tuple>
24
25		namespace LOG4CXX_NS
26		{
27
28		/**
29		* Configures the repository from environmental settings and files.
30		*
31		*/
32		class LOG4CXX_EXPORT DefaultConfigurator
33		{
34		private:
35	0	DefaultConfigurator() {}
36
37		public:
38		/**
39		Configure \c repository.
40
41		If the configuration file name has not been provided by a call to setConfigurationFileName(),
42		the environment variable "LOG4CXX_CONFIGURATION" or "log4j.configuration" value is used,
43		with ${varname} instances using either a system environment variable value (if found)
44		otherwise using the helpers::Properties object
45		provided by spi::Configurator::properties.
46
47		\usage
48		~~~
49		setenv LOG4CXX_CONFIGURATION="${PROGRAM_FILE_PATH.PARENT_PATH}/${PROGRAM_FILE_PATH.STEM}.xml"
50		~~~
51
52		Unless a custom configurator is specified using the
53		"LOG4CXX_CONFIGURATOR_CLASS" or "log4j.configuratorClass"
54		environment variable, the PropertyConfigurator will be used to
55		configure log4cxx unless the file name ends with the ".xml"
56		extension, in which case the DOMConfigurator will be used. If a
57		custom configurator is specified, the environment variable should
58		contain a fully qualified class name of a class that implements the
59		Configurator interface.
60
61		If the configuration file name is not found using any of the previous approaches,
62		the current directory is examined for a file with extension ".xml" or ".properties"
63		with a base name "log4cxx" or "log4j".
64
65		If a positive number has been provided by a call to setConfigurationWatchSeconds()
66		or the environment variables "LOG4CXX_CONFIGURATION_WATCH_SECONDS" contains a positive number
67		a background thread is started that will periodically check for a change to the configuration file
68		and apply any configuration changes found.
69
70		Call the spi::LoggerRepository::isConfigured \c repository member function
71		to determine whether a configuration file was found.
72		*/
73		static void configure(spi::LoggerRepositoryPtr repository);
74
75		/**
76		Attempt configuration by calling configure() passing the default repository.
77
78		See configure() for how the configuration file name is determined.
79
80		@return a success indicator.
81		*/
82		static spi::ConfigurationStatus tryConfigure();
83
84		/**
85		Make \c path the configuration file used by configure().
86
87		Any ${varname} instances in the \c path value are expanded
88		using either a system environment variable value (if found)
89		otherwise using the map provided by spi::Configurator::properties.
90
91		\usage
92		~~~{.cpp}
93		DefaultConfigurator::setConfigurationFileName(LOG4CXX_STR("${PROGRAM_FILE_PATH.PARENT_PATH}/${PROGRAM_FILE_PATH.STEM}.xml"))
94		~~~
95
96		*/
97		static void setConfigurationFileName(const LogString& path);
98
99		/**
100		Make \c seconds the time a background thread will delay before checking
101		for a change to the configuration file used by configure().
102
103		\usage
104		~~~{.cpp}
105		DefaultConfigurator::setConfigurationWatchSeconds(1);
106		~~~
107		*/
108		static void setConfigurationWatchSeconds(int seconds);
109
110		/**
111		* Call configure() passing the default repository
112		* after calling setConfigurationFileName() with a path composed of
113		* an entry in \c directories and an entry in \c filenames
114		* when the combination identifies an existing file.
115		*
116		\usage
117		~~~{.cpp}
118		std::vector<LogString> directories
119		{ LOG4CXX_STR(".")
120		, LOG4CXX_STR("${PROGRAM_FILE_PATH.PARENT_PATH}")
121		};
122		std::vector<LogString> filenames
123		{ LOG4CXX_STR("${PROGRAM_FILE_PATH.STEM}.xml")
124		, LOG4CXX_STR("${PROGRAM_FILE_PATH.STEM}.properties")
125		, LOG4CXX_STR("log4cxx.xml")
126		};
127		DefaultConfigurator::configureFromFile(directories, filenames);
128		~~~
129		*
130		* Using the above example and an executable file named "myapp"
131		* installed in the directory "/opt/com.foo/bin",
132		* locations are checked in the following order:
133		* -# "./myapp.xml"
134		* -# "./myapp.properties"
135		* -# "./log4cxx.xml"
136		* -# "/opt/com.foo/bin/myapp.xml"
137		* -# "/opt/com.foo/bin/myapp.properties"
138		* -# "/opt/com.foo/bin/log4cxx.xml"
139		*
140		* If a file exists but it is not able to be used to configure Log4cxx,
141		* the next file in the combinatorial set will be tried until
142		* a valid configuration file is found or
143		* all values in the combinatorial set have been tried.
144		*
145		* @param directories The directories to look in.
146		* @param filenames The names of the files to look for
147		* @return a success indicator and the configuration file path that was used (if found).
148		*/
149		static std::tuple<spi::ConfigurationStatus,LogString> configureFromFile
150		( const std::vector<LogString>& directories
151		, const std::vector<LogString>& filenames
152		);
153
154		private:
155		static const LogString getConfigurationFileName();
156		static const LogString getConfiguratorClass();
157		static int getConfigurationWatchDelay();
158
159		}; // class DefaultConfigurator
160		} // namespace log4cxx
161
162		#endif //_LOG4CXX_DEFAULT_CONFIGURATOR_H

Coverage Report

Created: 2026-03-12 07:00