class Poco::Util::ServerApplication
Overview
A subclass of the Application class that is used for implementing server applications. More…
#include <ServerApplication.h> class ServerApplication: public Poco::Util::Application { public: // methods bool isInteractive() const; int run( int argc, char** argv ); int run(const std::vector<std::string>& args); static void terminate(); protected: // methods virtual int run(); void waitForTerminationRequest(); virtual void defineOptions(OptionSet& options); };
Inherited Members
public: // typedefs typedef std::vector<std::string> ArgVec; typedef Poco::AutoPtr<Subsystem> SubsystemPtr; typedef std::vector<SubsystemPtr> SubsystemVec; // enums enum ConfigPriority; enum ExitCode; // methods void duplicate() const; void release() const; int referenceCount() const; virtual const char* name() const = 0; void addSubsystem(Subsystem* pSubsystem); void init( int argc, char* argv [] ); void init(const ArgVec& args); bool initialized() const; void setUnixOptions(bool flag); int loadConfiguration(int priority = PRIO_DEFAULT); void loadConfiguration( const std::string& path, int priority = PRIO_DEFAULT ); template <class C> C& getSubsystem() const; SubsystemVec& subsystems(); virtual int run(); std::string commandName() const; std::string commandPath() const; LayeredConfiguration& config() const; Poco::Logger& logger() const; const ArgVec& argv() const; const OptionSet& options() const; const Poco::Timestamp& startTime() const; Poco::Timespan uptime() const; void stopOptionsProcessing(); virtual const char* name() const; static Application& instance(); protected: // methods virtual void initialize(Application& app) = 0; virtual void uninitialize() = 0; virtual void reinitialize(Application& app); virtual void defineOptions(OptionSet& options); virtual void initialize(Application& self); virtual void uninitialize(); virtual void reinitialize(Application& self); virtual void defineOptions(OptionSet& options); virtual void handleOption( const std::string& name, const std::string& value ); void setLogger(Poco::Logger& logger); virtual int main(const std::vector<std::string>& args); bool findFile(Poco::Path& path) const; void init();
Detailed Documentation
A subclass of the Application class that is used for implementing server applications.
A ServerApplication allows for the application to run as a Windows service or as a Unix daemon without the need to add extra code.
For a ServerApplication to work both from the command line and as a daemon or service, a few rules must be met:
- Subsystems must be registered in the constructor. - All non-trivial initializations must be made in the initialize() method. - At the end of the main() method, waitForTerminationRequest() should be called. - New threads must only be created in initialize() or main() or methods called from there, but not in the application class' constructor or in the constructor of instance variables. The reason for this is that fork() will be called in order to create the daemon process, and threads created prior to calling fork() won't be taken over to the daemon process. - The main(argc, argv) function must look as follows: int main(int argc, char** argv) { MyServerApplication app; return app.run(argc, argv); }
The POCO_SERVER_MAIN macro can be used to implement main(argc, argv). If POCO has been built with POCO_WIN32_UTF8, POCO_SERVER_MAIN supports Unicode command line arguments.
On Windows platforms, an application built on top of the ServerApplication class can be run both from the command line or as a service.
To run an application as a Windows service, it must be registered with the Windows Service Control Manager (SCM). To do this, the application can be started from the command line, with the /registerService option specified. This causes the application to register itself with the SCM, and then exit. Similarly, an application registered as a service can be unregistered, by specifying the /unregisterService option. The file name of the application executable (excluding the .exe suffix) is used as the service name. Additionally, a more user-friendly name can be specified, using the /displayName option (e.g., /displayName=”Demo Service”) and a service description can be added with the /description option. The startup mode (automatic or manual) for the service can be specified with the /startup option.
An application can determine whether it is running as a service by checking for the “application.runAsService” configuration property.
if (config().getBool("application.runAsService", false)) { // do service specific things }
Note that the working directory for an application running as a service is the Windows system directory (e.g., C:). Take this into account when working with relative filesystem paths. Also, services run under a different user account, so an application that works when started from the command line may fail to run as a service if it depends on a certain environment (e.g., the PATH environment variable).
An application registered as a Windows service can be started with the NET START <name> command and stopped with the NET STOP <name> command. Alternatively, the Services MMC applet can be used.
On Unix platforms, an application built on top of the ServerApplication class can be optionally run as a daemon by giving the daemon command line option. A daemon, when launched, immediately forks off a background process that does the actual work. After launching the background process, the foreground process exits.
After the initialization is complete, but before entering the main() method, the current working directory for the daemon process is changed to the root directory (“/”), as it is common practice for daemon processes. Therefore, be careful when working with files, as relative paths may not point to where you expect them point to.
An application can determine whether it is running as a daemon by checking for the “application.runAsDaemon” configuration property.
if (config().getBool("application.runAsDaemon", false)) { // do daemon specific things }
When running as a daemon, specifying the pidfile option (e.g., pidfile=/var/run/sample.pid) may be useful to record the process ID of the daemon in a file. The PID file will be removed when the daemon process terminates (but not, if it crashes).
Methods
bool isInteractive() const
Returns true if the application runs from the command line.
Returns false if the application runs as a Unix daemon or Windows service.
int run( int argc, char** argv )
Runs the application by performing additional initializations and calling the main() method.
int run(const std::vector<std::string>& args)
Runs the application by performing additional initializations and calling the main() method.
static void terminate()
Sends a friendly termination request to the application.
If the application’s main thread is waiting in waitForTerminationRequest(), this method will return and the application can shut down.
virtual int run()
Runs the application by performing additional (un)initializations and calling the main() method.
First calls initialize(), then calls main(), and finally calls uninitialize(). The latter will be called even if main() throws an exception. If initialize() throws an exception, main() will not be called and the exception will be propagated to the caller. If uninitialize() throws an exception, the exception will be propagated to the caller.
virtual void defineOptions(OptionSet& options)
Called before command line processing begins.
If a subclass wants to support command line arguments, it must override this method. The default implementation does not define any options itself, but calls defineOptions() on all registered subsystems.
Overriding implementations should call the base class implementation.