Poco::Util

class Application

Library: Util
Package: Application
Header: Poco/Util/Application.h

Description

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:

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:

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

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.

Inheritance

Direct Base Classes: Subsystem

All Base Classes: Poco::RefCountedObject, Subsystem

Known Derived Classes: ServerApplication

Member Summary

Member Functions: addSubsystem, commandName, config, defineOptions, findFile, getSubsystem, handleOption, init, initialize, initialized, instance, loadConfiguration, logger, main, name, options, reinitialize, run, setLogger, setUnixOptions, startTime, stopOptionsProcessing, uninitialize, uptime

Inherited Functions: defineOptions, duplicate, initialize, name, referenceCount, reinitialize, release, uninitialize

Enumerations

ConfigPriority

PRIO_APPLICATION = - 100

PRIO_DEFAULT = 0

PRIO_SYSTEM = 100

ExitCode

Commonly used exit status codes. Based on the definitions in the 4.3BSD <sysexits.h> header file.

EXIT_OK = 0

successful termination

EXIT_USAGE = 64

command line usage error

EXIT_DATAERR = 65

data format error

EXIT_NOINPUT = 66

cannot open input

EXIT_NOUSER = 67

addressee unknown

EXIT_NOHOST = 68

host name unknown

EXIT_UNAVAILABLE = 69

service unavailable

EXIT_SOFTWARE = 70

internal software error

EXIT_OSERR = 71

system error (e.g., can't fork)

EXIT_OSFILE = 72

critical OS file missing

EXIT_CANTCREAT = 73

can't create (user) output file

EXIT_IOERR = 74

input/output error

EXIT_TEMPFAIL = 75

temp failure; user is invited to retry

EXIT_PROTOCOL = 76

remote error in protocol

EXIT_NOPERM = 77

permission denied

EXIT_CONFIG = 78

configuration error

Constructors

Application

Application();

Creates the Application.

Application

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

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

Destructor

~Application protected virtual

~Application();

Destroys the Application and deletes all registered subsystems.

Member Functions

addSubsystem

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.

commandName

std::string commandName() const;

Returns the command name used to invoke the application.

config inline

LayeredConfiguration & config() const;

Returns the application's configuration.

getSubsystem inline

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.

init

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

Initializes the application and all registered subsystems, using the given command line arguments.

init

void init(
    int argc,
    wchar_t * argv[]
);

Initializes the application and all registered subsystems, using the given command line arguments.

This Windows-specific version of init is used for passing Unicode command line arguments from wmain().

init

void init(
    const std::vector < std::string > & args
);

Initializes the application and all registered subsystems, using the given command line arguments.

initialized inline

bool initialized() const;

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

instance static inline

static Application & instance();

Returns a reference to the Application singleton.

Throws a NullPointerException if no Application instance exists.

loadConfiguration

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 initialize(argc, argv) has been called.

loadConfiguration

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:

Extensions are not case sensitive.

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

logger inline

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".

name virtual

const char * name() const;

See also: Poco::Util::Subsystem::name()

options inline

const OptionSet & options() const;

Returns the application's option set.

run virtual

virtual int run();

Runs the application by performing additional initializations and calling the main() method.

setUnixOptions

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.

startTime inline

const Poco::Timestamp & startTime() const;

Returns the application start time (UTC).

stopOptionsProcessing

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.

uptime inline

Poco::Timespan uptime() const;

Returns the application uptime.

defineOptions protected virtual

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.

See also: Poco::Util::Subsystem::defineOptions()

findFile protected

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.

handleOption protected virtual

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.

init protected

void init();

Common initialization code.

initialize protected 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.

See also: Poco::Util::Subsystem::initialize()

main protected virtual

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.

reinitialize protected 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.

See also: Poco::Util::Subsystem::reinitialize()

setLogger protected

void setLogger(
    Poco::Logger & logger
);

Sets the logger used by the application.

uninitialize protected 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.

See also: Poco::Util::Subsystem::uninitialize()

POCO C++ Libraries 1.3.6-all
Copyright © 2009, Applied Informatics Software Engineering GmbH and Contributors