1
0
Fork 0
arangodb/ApplicationServer/ApplicationServerImpl.h

627 lines
22 KiB
C++

////////////////////////////////////////////////////////////////////////////////
/// @brief application server implementation
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2010-2011 triagens GmbH, Cologne, Germany
///
/// Licensed 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.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Dr. Frank Celler
/// @author Copyright 2009-2011, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////
#ifndef TRIAGENS_FYN_APPLICATION_SERVER_APPLICATION_SERVER_IMPL_H
#define TRIAGENS_FYN_APPLICATION_SERVER_APPLICATION_SERVER_IMPL_H 1
#include <Basics/Common.h>
#include <Basics/ProgramOptions.h>
#include <Basics/ProgramOptionsDescription.h>
#include "ApplicationServer/ApplicationServer.h"
////////////////////////////////////////////////////////////////////////////////
/// @page CommandLineLoggingTOC
///
/// <ol>
/// <li>General Logging Options</li>
/// <ol>
/// <li>log.file</li>
/// <li>log.severity</li>
/// <li>log.syslog</li>
/// </ol>
/// <li>Human Readable Logging</li>
/// <ol>
/// <li>log.level</li>
/// <li>log.line-number</li>
/// <li>log.prefix</li>
/// <li>log.thread</li>
/// </ol>
/// <li>Machine Readable Logging</li>
/// <ol>
/// <li>log.application</li>
/// <li>log.facility</li>
/// <li>log.format</li>
/// <li>log.hostname</li>
/// </ol>
/// </ol>
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @page CommandLineLogging Command-Line Options for Logging
///
/// There are two different kinds of logs. Human-readable logs and
/// machine-readable logs. The human-readable logs are used to provide an
/// administration with information about the server. The machine-readable logs
/// are used to provide statistics about executed requests and timings about
/// computation steps.
///
/// <hr>
/// @copydoc CommandLineLoggingTOC
///
/// @section GeneralLogging General Logging Options
///
/// @copydetails triagens::rest::ApplicationServerImpl::logFile
///
/// @copydetails triagens::rest::ApplicationServerImpl::logSeverity
///
/// @copydetails triagens::rest::ApplicationServerImpl::logSyslog
///
/// @section HumanReadableLogging Human Readable Logging
///
/// @copydetails triagens::rest::ApplicationServerImpl::logLevel
///
/// @copydetails triagens::rest::ApplicationServerImpl::logLineNumber
///
/// @copydetails triagens::rest::ApplicationServerImpl::logPrefix
///
/// @copydetails triagens::rest::ApplicationServerImpl::logThreadId
///
/// @section MaschineReadableLogging Maschine Readable Logging
///
/// @copydetails triagens::rest::ApplicationServerImpl::logApplicationName
///
/// @copydetails triagens::rest::ApplicationServerImpl::logFacility
///
/// @copydetails triagens::rest::ApplicationServerImpl::logFormat
///
/// @copydetails triagens::rest::ApplicationServerImpl::logHostName
///
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @page CommandLineRandomTOC
///
/// <ol>
/// <li>random.generator</li>
/// <li>random.no-seed</li>
/// </ol>
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @page CommandLineRandom Command-Line Options for Random Numbers
///
/// @copydoc CommandLineRandomTOC
/// <hr>
///
/// @copydetails triagens::rest::ApplicationServerImpl::randomGenerator
////////////////////////////////////////////////////////////////////////////////
namespace triagens {
namespace rest {
////////////////////////////////////////////////////////////////////////////////
/// @brief application server implementation
////////////////////////////////////////////////////////////////////////////////
class ApplicationServerImpl : virtual public ApplicationServer {
public:
////////////////////////////////////////////////////////////////////////////////
/// @brief constructor
////////////////////////////////////////////////////////////////////////////////
ApplicationServerImpl (string const& description, string const& version);
////////////////////////////////////////////////////////////////////////////////
/// @brief destructor
////////////////////////////////////////////////////////////////////////////////
~ApplicationServerImpl ();
public:
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void addFeature (ApplicationFeature*);
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void setSystemConfigFile (string const& name) {
systemConfigFile = name;
}
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void setUserConfigFile (string const& name) {
userConfigFile = name;
}
public:
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
basics::ProgramOptions& programOptions () {
return options;
}
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
vector<string> programArguments () {
return arguments;
}
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
bool parse (int argc, char* argv[], map<string, basics::ProgramOptionsDescription>);
public:
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void start ();
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void wait ();
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void beginShutdown ();
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
////////////////////////////////////////////////////////////////////////////////
void shutdown ();
protected:
////////////////////////////////////////////////////////////////////////////////
/// @brief add options to description
////////////////////////////////////////////////////////////////////////////////
virtual void setupOptions (map<string, basics::ProgramOptionsDescription>&);
////////////////////////////////////////////////////////////////////////////////
/// @brief parsing phase 1, before config file
////////////////////////////////////////////////////////////////////////////////
virtual bool parsePhase1 ();
////////////////////////////////////////////////////////////////////////////////
/// @brief parsing phase 2, after config file
////////////////////////////////////////////////////////////////////////////////
virtual bool parsePhase2 ();
protected:
////////////////////////////////////////////////////////////////////////////////
/// @brief program options
///
/// @CMDOPT{--help}
///
/// @CMDOPT{-h}
///
/// Prints a list of the most common options available and then
/// exits. In order to see all options use @CODE{--help-all}.
////////////////////////////////////////////////////////////////////////////////
basics::ProgramOptions options;
////////////////////////////////////////////////////////////////////////////////
/// @brief defined features
////////////////////////////////////////////////////////////////////////////////
vector<ApplicationFeature*> features;
private:
void setupLogging ();
bool readConfigurationFile ();
void dropPriviliges ();
private:
string title;
////////////////////////////////////////////////////////////////////////////////
/// @brief program options
///
/// @CMDOPT{--version}
///
/// @CMDOPT{-v}
///
/// Prints the version of the server and exits.
////////////////////////////////////////////////////////////////////////////////
string version;
////////////////////////////////////////////////////////////////////////////////
/// @brief config file
///
/// @CMDOPT{--configuration @CA{filename}}
///
/// @CMDOPT{-c @CA{filename}}
///
/// Specifies the name of the configuration file to use.
///
/// If this command is not passed to the server, then by default, the server
/// will attempt to first locate a file named @CODE{~/SERVER/SERVER.conf} in the
/// user's home directory, where @CA{SERVER} is the name of the corresponding
/// server.
///
/// If no such file is found, the server will proceed to look for a file
/// @CODE{/etc/SERVER.conf} in the system configuration directory. The default
/// installation specifies the system configuration directory as
/// /etc. Therefore, in case that no configuration file is found in the user's
/// home directory, the server will proceed to look for a file named
/// @CODE{/etc/SERVER.conf}.
///
/// Only command line options with a value should be set within the
/// configuration file. Command line options which act as flags should be
/// entered on the command line when starting the server.
///
/// White space is ignored. Each option is specified on a separate line in the
/// form
///
/// @verbinclude conf1
///
/// Alternatively, a header section can be specified and options pertaining to
/// that section can be specified in a shorter form
///
/// @verbinclude conf2
///
/// rather than specifying
///
/// @verbinclude conf3
///
/// Comments can be placed in the configuration file, only if the line begins
/// with one or more hash symbols (#).
///
/// There may be occasions where a configuration file exists and the user wishes
/// to override configuration settings stored in a configuration file. Any
/// settings specified on the command line will overwrite the same setting when
/// it appears in a configuration file. If the user wishes to completely ignore
/// configuration files without necessarily deleting the file (or files), then
/// add the command line option
///
/// @verbinclude conf4
///
/// or
///
/// @verbinclude conf5
///
/// when starting up the server. Note that, the word @CODE{none} is
/// case-insensitive.
////////////////////////////////////////////////////////////////////////////////
string initFile;
string userConfigFile;
string systemConfigFile;
////////////////////////////////////////////////////////////////////////////////
/// @brief the user id to use for the process
///
/// @CMDOPT{--uid @CA{uid}}
///
/// The name (identity) of the user the server will run as. If this parameter is
/// not specified, the server will not attempt to change its UID, so that the
/// UID used by the server will be the same as the UID of the user who started
/// the server. If this parameter is specified, then the server will change its
/// UID after opening ports and reading configuration files, but before
/// accepting connections or opening other files (such as recovery files). This
/// is useful when the server must be started with raised privileges (in certain
/// environments) but security considerations require that these privileges be
/// dropped once the server has started work.
///
/// Observe that this parameter cannot be used to bypass operating system
/// security. In general, this parameter (and its corresponding relative gid)
/// can lower privileges but not raise them.
////////////////////////////////////////////////////////////////////////////////
string uid;
////////////////////////////////////////////////////////////////////////////////
/// @brief the group id to use for the process
///
/// @CMDOPT{--gid @CA{gid}}
///
/// The name (identity) of the group the server will run as. If this parameter
/// is not specified, then the server will not attempt to change its GID, so
/// that the GID the server runs as will be the primary group of the user who
/// started the server. If this parameter is specified, then the server will
/// change its GID after opening ports and reading configuration files, but
/// before accepting connections or opening other files (such as recovery
/// files).
///
/// This parameter is related to the parameter uid.
////////////////////////////////////////////////////////////////////////////////
string gid;
////////////////////////////////////////////////////////////////////////////////
/// @brief log application name
///
/// @CMDOPT{--log.application @CA{name}}
///
/// Specifies the @CA{name} of the application which should be logged if this item of
/// information is to be logged.
////////////////////////////////////////////////////////////////////////////////
string logApplicationName;
////////////////////////////////////////////////////////////////////////////////
/// @brief log host name
///
/// @CMDOPT{--log.hostname @CA{name}}
///
/// Specifies the @CA{name} of the operating environment (the "hostname") which
/// should be logged if this item of information is to be logged. Note that
/// there is no default hostname.
////////////////////////////////////////////////////////////////////////////////
string logHostName;
////////////////////////////////////////////////////////////////////////////////
/// @brief log facility
///
/// @CMDOPT{--log.facility @CA{name}}
///
/// Specifies the name of the server instance which should be logged if this
/// item of information is to be logged.
////////////////////////////////////////////////////////////////////////////////
string logFacility;
////////////////////////////////////////////////////////////////////////////////
/// @brief log level
///
/// @CMDOPT{--log.level @CA{level}}
///
/// @CMDOPT{--log @CA{level}}
///
/// Allows the user to choose the level of information which is logged by the
/// server. The argument @CA{level} is specified as a string and can be one of
/// the values listed below. Note that, fatal errors, that is, errors which
/// cause the server to terminate, are always logged irrespective of the log
/// level assigned by the user. The variant @c log.level can be used in
/// configuration files, the variant @c log for command line options.
///
/// - fatal: Logs errors which cause the server to terminate.
///
/// Fatal errors generally indicate some inconsistency with the manner in which
/// the server has been coded. Fatal errors may also indicate a problem with the
/// platform on which the server is running. Fatal errors always cause the
/// server to terminate. For example,
///
/// @LIT{2010-09-20T07:32:12Z [4742] FATAL a http server has already been created}
///
/// - error: Logs errors which the server has encountered.
///
/// These errors may not necessarily result in the termination of the
/// server. For example,
///
/// @LIT{2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors'\, going to 'warning'}
///
/// - warning: Provides information on errors encountered by the server,
/// which are not necessarily detrimental to it's continued operation.
///
/// For example,
///
/// @LIT{2010-09-20T08:15:26Z [5533] WARNING got corrupted HTTP request 'POS?'}
///
/// Note that, setting the log level to warning will also result in all errors
/// to be logged as well.
///
/// - info: Logs information about the status of the server.
///
/// For example,
///
/// @LIT{2010-09-20T07:40:38Z [4998] INFO SimpleVOC ready for business}
///
/// Note that, setting the log level to info will also result in all errors and
/// warnings to be logged as well.
///
/// - debug: Logs all errors, all warnings and debug information.
///
/// Debug log information is generally useful to find out the state of the
/// server in the case of an error. For example,
///
/// @LIT{2010-09-17T13:02:53Z [13783] DEBUG opened port 7000 for any}
///
/// Note that, setting the log level to debug will also result in all errors,
/// warnings and server status information to be logged as well.
///
/// - trace: As the name suggests, logs information which may be useful to trace
/// problems encountered with using the server.
///
/// For example,
///
/// @LIT{2010-09-20T08:23:12Z [5687] TRACE trying to open port 8000}
///
/// Note that, setting the log level to trace will also result in all errors,
/// warnings, status information, and debug information to be logged as well.
////////////////////////////////////////////////////////////////////////////////
string logLevel;
////////////////////////////////////////////////////////////////////////////////
/// @brief log format
///
/// @CMDOPT{--log.format @CA{format}}
///
/// @copydetails triagens::basics::Logger::setLogFormat
////////////////////////////////////////////////////////////////////////////////
string logFormat;
////////////////////////////////////////////////////////////////////////////////
/// @brief log severity
///
/// @CMDOPT{--log.severity @CA{severity}}
///
/// This parameter provides a set of standard log severities which can be
/// used. The current arguments accepted are:
///
/// - exception
/// - technical
/// - functional
/// - development
/// - human
/// - all (human and non-human)
/// - non-human (exception, technical, functional, and development)
///
/// The default is all.
////////////////////////////////////////////////////////////////////////////////
string logSeverity;
////////////////////////////////////////////////////////////////////////////////
/// @brief log level
///
/// @CMDOPT{--log.file @CA{filename}}
///
/// This option allows the user to specify the name of a file to which
/// information is logged. By default, if no log file is specified, the standard
/// output is used. Note that, if the file named by @CA{filename} does not
/// exist, it will be created. However, if the file already exists, output is
/// appended to the file. Use @LIT{+} to log to standard error. Use @LIT{-} to
/// log to standard output. Use @LIT{""} to disable logging to file.
////////////////////////////////////////////////////////////////////////////////
string logFile;
////////////////////////////////////////////////////////////////////////////////
/// @brief log prefix
///
/// @CMDOPT{--log.prefix @CA{prefix}}
///
/// This option is used specify an prefix to logged text.
////////////////////////////////////////////////////////////////////////////////
string logPrefix;
////////////////////////////////////////////////////////////////////////////////
/// @brief log level
///
/// @CMDOPT{--log.syslog @CA{arg}}
///
/// If this option is set, then in addition to output being directed to the
/// standard output (or to a specified file, in the case that the command line
/// log.file option was set), log output is also sent to the system logging
/// facility. The @CA{arg} is the system log facility to use. See syslog for
/// further details.
////////////////////////////////////////////////////////////////////////////////
string logSyslog;
////////////////////////////////////////////////////////////////////////////////
/// @brief log thread identifier
///
/// @CMDOPT{--log.thread}
///
/// Whenever log output is generated, the process ID is written as part of the
/// log information. Setting this option appends the thread id of the calling
/// thread to the process id. For example,
///
/// @LIT{2010-09-20T13:04:01Z [19355] INFO ready for business}
///
/// when no thread is logged and
///
/// @LIT{2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business}
///
/// when this command line option is set.
////////////////////////////////////////////////////////////////////////////////
bool logThreadId;
////////////////////////////////////////////////////////////////////////////////
/// @brief log line number
///
/// @CMDOPT{--log.line-number}
///
/// Normally, if an human readable fatal, error, warning or info message is
/// logged, no information about the file and line number is provided. The file
/// and line number is only logged for debug and trace message. This option can
/// be use to always log these pieces of information.
////////////////////////////////////////////////////////////////////////////////
bool logLineNumber;
////////////////////////////////////////////////////////////////////////////////
/// @brief random number generator to use
///
/// @CMDOPT{--random.generator @CA{arg}}
///
/// The argument is an integer (1,2,3 or 4) which sets the manner in which
/// random numbers are generated. The default method (3) is to use the a
/// non-blocking random (or pseudorandom) number generator supplied by the
/// operating system. Specifying an argument of 2, uses a blocking random (or
/// pseudorandom) number generator. Specifying an argument 1 sets a pseudorandom
/// number generator using an implication of the Mersenne Twister MT19937
/// algorithm. Algorithm 4 is a combination of the blocking random number
/// generator and the Mersenne Twister.
///
/// @CMDOPT{--random.no-seed}
///
/// By default, the random generator is seeded. Setting this option causes the
/// random number generator not to be seeded. (Seeding the random number
/// generator only occurs if the generator is set to Mersenne, refer to
/// random.generator for details.)
////////////////////////////////////////////////////////////////////////////////
uint32_t randomGenerator;
basics::ProgramOptionsDescription description;
basics::ProgramOptionsDescription descriptionFile;
vector<string> arguments;
};
}
}
#endif