class Poco::Util::Application

Overview

The Application class implements the main subsystem in a process. More…

#include <Application.h>

class Application: public Poco::Util::Subsystem
{
public:
    // typedefs

    typedef std::vector<std::string> ArgVec;
    typedef Poco::AutoPtr<Subsystem> SubsystemPtr;
    typedef std::vector<SubsystemPtr> SubsystemVec;

    // enums

    enum ConfigPriority;
    enum ExitCode;

    // construction

    Application();

    Application(
        int argc,
        char* argv []
        );

    // methods

    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& 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();
};

// direct descendants

class ServerApplication;

Inherited Members

public:
    // methods

    void
    duplicate() const;

    void
    release() const;

    int
    referenceCount() const;

    virtual
    const char*
    name() const = 0;

protected:
    // methods

    virtual
    void
    initialize(Application& app) = 0;

    virtual
    void
    uninitialize() = 0;

    virtual
    void
    reinitialize(Application& app);

    virtual
    void
    defineOptions(OptionSet& options);

Detailed Documentation

The Application class implements the main subsystem in a process.

The application class is responsible for initializing all its subsystems.

Subclasses can and should override the following virtual methods:

- initialize() (the one-argument, protected variant)
- uninitialize()
- reinitialize()
- defineOptions()
- handleOption()
- main()

The application’s main logic should be implemented in the main() method.

There may be at most one instance of the Application class in a process.

The Application class maintains a LayeredConfiguration (available via the config() member function) consisting of:

- a MapConfiguration (priority -100) storing application-specific
  properties, as well as properties from bound command line arguments.
- a SystemConfiguration (priority 100)
- the configurations loaded with loadConfiguration().

The Application class sets a few default properties in its configuration. These are:

- application.path: the absolute path to application executable
- application.name: the file name of the application executable
- application.baseName: the file name (excluding extension) of the application executable
- application.dir: the path to the directory where the application executable resides
- application.configDir: the path to the directory where the last configuration file loaded with loadConfiguration() was found.

If loadConfiguration() has never been called, application.configDir will be equal to application.dir.

The POCO_APP_MAIN macro can be used to implement main(argc, argv). If POCO has been built with POCO_WIN32_UTF8, POCO_APP_MAIN supports Unicode command line arguments.

Construction

Application()

Creates the Application.

Application(
    int argc,
    char* argv []
    )

Creates the Application and calls init(argc, argv).

Methods

void
addSubsystem(Subsystem* pSubsystem)

Adds a new subsystem to the application.

The application immediately takes ownership of it, so that a call in the form

Application::instance().addSubsystem(new MySubsystem);

is okay.

void
init(
    int argc,
    char* argv []
    )

Processes the application’s command line arguments and sets the application’s properties (e.g., “application.path”, “application.name”, etc.).

Note that as of release 1.3.7, init() no longer calls initialize(). This is now called from run().

void
init(const ArgVec& args)

Processes the application’s command line arguments and sets the application’s properties (e.g., “application.path”, “application.name”, etc.).

Note that as of release 1.3.7, init() no longer calls initialize(). This is now called from run().

bool
initialized() const

Returns true iff the application is in initialized state (that means, has been initialized but not yet uninitialized).

void
setUnixOptions(bool flag)

Specify whether command line option handling is Unix-style (flag == true; default) or Windows/OpenVMS-style (flag == false).

This member function should be called from the constructor of a subclass to be effective.

int
loadConfiguration(int priority = PRIO_DEFAULT)

Loads configuration information from a default location.

The configuration(s) will be added to the application’s LayeredConfiguration with the given priority.

The configuration file(s) must be located in the same directory as the executable or a parent directory of it, and must have the same base name as the executable, with one of the following extensions: .properties, .ini or .xml.

The .properties file, if it exists, is loaded first, followed by the .ini file and the .xml file.

If the application is built in debug mode (the _DEBUG preprocessor macro is defined) and the base name of the appication executable ends with a ‘d’, a config file without the ‘d’ ending its base name is also found.

Example: Given the application “SampleAppd.exe”, built in debug mode. Then loadConfiguration() will automatically find a configuration file named “SampleApp.properties” if it exists and if “SampleAppd.properties” cannot be found.

Returns the number of configuration files loaded, which may be zero.

This method must not be called before init(argc, argv) has been called.

void
loadConfiguration(
    const std::string& path,
    int priority = PRIO_DEFAULT
    )

Loads configuration information from the file specified by the given path.

The file type is determined by the file extension. The following extensions are supported:

- .properties - properties file (PropertyFileConfiguration)
- .ini        - initialization file (IniFileConfiguration)
- .xml        - XML file (XMLConfiguration)

Extensions are not case sensitive.

The configuration will be added to the application’s LayeredConfiguration with the given priority.

template <class C>
C&
getSubsystem() const

Returns a reference to the subsystem of the class given as template argument.

Throws a NotFoundException if such a subsystem has not been registered.

SubsystemVec&
subsystems()

Returns a reference to the subsystem list.

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.

std::string
commandName() const

Returns the command name used to invoke the application.

std::string
commandPath() const

Returns the full command path used to invoke the application.

LayeredConfiguration&
config() const

Returns the application’s configuration.

Poco::Logger&
logger() const

Returns the application’s logger.

Before the logging subsystem has been initialized, the application’s logger is “ApplicationStartup”, which is connected to a ConsoleChannel.

After the logging subsystem has been initialized, which usually happens as the first action in Application::initialize(), the application’s logger is the one specified by the “application.logger” configuration property. If that property is not specified, the logger is “Application”.

const ArgVec&
argv() const

Returns reference to vector of the application’s arguments as specified on the command line.

If user overrides the Application::main(const ArgVec&) function, it will receive only the command line parameters that were not processed in Application::processOptons(). This function returns the full set of command line parameters as received in main(argc, argv*).

const OptionSet&
options() const

Returns the application’s option set.

const Poco::Timestamp&
startTime() const

Returns the application start time (UTC).

Poco::Timespan
uptime() const

Returns the application uptime.

void
stopOptionsProcessing()

If called from an option callback, stops all further options processing.

If called, the following options on the command line will not be processed, and required options will not be checked.

This is useful, for example, if an option for displaying help information has been encountered and no other things besides displaying help shall be done.

virtual
const char*
name() const

Returns the name of the subsystem.

Must be implemented by subclasses.

static
Application&
instance()

Returns a reference to the Application singleton.

Throws a NullPointerException if no Application instance exists.

virtual
void
initialize(Application& self)

Initializes the application and all registered subsystems.

Subsystems are always initialized in the exact same order in which they have been registered.

Overriding implementations must call the base class implementation.

virtual
void
uninitialize()

Uninitializes the application and all registered subsystems.

Subsystems are always uninitialized in reverse order in which they have been initialized.

Overriding implementations must call the base class implementation.

virtual
void
reinitialize(Application& self)

Re-nitializes the application and all registered subsystems.

Subsystems are always reinitialized in the exact same order in which they have been registered.

Overriding implementations must call the base class implementation.

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.

virtual
void
handleOption(
    const std::string& name,
    const std::string& value
    )

Called when the option with the given name is encountered during command line arguments processing.

The default implementation does option validation, bindings and callback handling.

Overriding implementations must call the base class implementation.

void
setLogger(Poco::Logger& logger)

Sets the logger used by the application.

virtual
int
main(const std::vector<std::string>& args)

The application’s main logic.

Unprocessed command line arguments are passed in args. Note that all original command line arguments are available via the properties application.argc and application.argv[<n>].

Returns an exit code which should be one of the values from the ExitCode enumeration.

bool
findFile(Poco::Path& path) const

Searches for the file in path in the application directory.

If path is absolute, the method immediately returns true and leaves path unchanged.

If path is relative, searches for the file in the application directory and in all subsequent parent directories. Returns true and stores the absolute path to the file in path if the file could be found. Returns false and leaves path unchanged otherwise.

void
init()

Common initialization code.