NAME

NetSDS::App - common application superclass

SYNOPSIS

        MyApp->run(
                conf_file => '/etc/NetSDS/myapp.conf',
                daemon => 1,
                use_pidfile => 1,
        );

        package MyApp;

        use base 'NetSDS::App';

        sub process {
                my ($this) = @_;
                print "Hello!";
        }

DESCRIPTION

NetSDS::App provides common application functionality implemented as superclass to inherit real applications from it.

Common application workflow is looking like this:

        start()
                |
        process()
                |
        stop()

It may be redefined in main_loop() method if necessary. But about 90% of applications will match this scheme.

So if you need to implement some common logic, it's necessary to rewrite start(), process() and stop() methods.

CONSTRUCTOR AND CLASS METHODS

new([%params])

Constructor is usually invoked from run() class method. It creates application object and set its initial properties from oarameters passed as hash.

Standard parameters are:

        * name - application name
        * debug - set to 1 for debugging
        * daemon - set to 1 for daemonization
        * verbose - set to 1 for more verbosity
        * use_pidfile - set to 1 for PID files processing
        * pid_dir - path to PID files catalog
        * conf_file - path to configuration file
        * has_conf - set to 1 if configuration file is necessary
        * auto_features - set to 1 for auto features inclusion
        * infinite - set to 1 for inifinite loop

run(%parameters)

This method calls class constructor and then switch to main_loop() method.

All method parameters are transparently passed to application constructor.

        MyApp->run(
                conf_file => '/etc/myapp.conf',
                daemon => 1,
        );
        1;

        package MyApp;
        use base 'NetSDS::App';
        1;

OBJECT METHODS

name([$name]) - application name

This method is an accessor to application name allowing to retrieve this or set new one.

        print "My name is " . $this->name;

pid() - PID of application process

Read only access to process identifier (PID).

        print "My PID is " . $this->pid;

debug() - debugging flag

This method provides an accessor to debugging flag. If application called with --debug option it will return TRUE value.

        if ($this->debug) {
                print "Debug info: " . $debug_data;
        }

verbose() - verbosity flag

This method provides an accessor to verbosity flag.

It may be used to increase application verbosity level if necessary.

        if ($this->verbose) {
                print "I'm working!";
        };

NOTE: This flag is is for normal operations. If you need implement debug output or other development/testing functionality - use debug() instead.

logger() - accessor to logger

This method is accessor to logger (object of NetSDS::Logger class).

NOTE: There is no need to use this method directly in application. See log() method description to understand logging features.

conf() - accessor to configuration

This method is accessor to application configuration represented as hash reference returned by NetSDS::Conf module.

Configuration sample:

        ------------------------
        content_dir /var/lib/content

        <kannel>
                send_url http://127.0.0.1:13013/
                login netsds
                passwd topsecret
        </kannel>
        ------------------------

Code sample:

        # Retrieve configuration
        my $content_dir = $this->conf->{content_dir};
        my $kannel_url = $this->conf->{kannel}->{send_url};

use_pidfile(BOOL) - PID file checking flag

Paramters: TRUE if PID file checking required

pid_dir([$directory]) - PID files storage

Paramters: directory name

        $app->pid_dir("/var/run");

daemon(BOOL) - daemonization flag

Paramters: TRUE if application should be a daemon

        if ($this->daemon()) {
                $this->log("info", "Yeah! I'm daemon!");
        };

auto_features() - auto features flag

Automatic features inclusion allowed if TRUE.

infinite([$bool]) - is application in infinite loop

$app->infinite(1); # set infinite loop

initialize()

Common application initialization:

1. Reading config if necessary.

2. Daemonize application.

3. Check PID file for already running application instances.

4. Start logger.

5. Prepare default signal handlers.

use_auto_features() - add features to application

This method implements automatic features inclusion by application configuration file (see feature sections).

add_feature($name, $class, $config, %params) - add feature

Paramters: feature name, class name, parameters (optional)

Returns: feature object

        $this->add_feature('kannel','NetSDS::Feature::Kannel', $this->conf->{feature}->{kannel});
        $this->kannel->send(.....);

finalize() - switch to finalization stage

This method called if we need to finish application.

start() - user defined initialization

Abstract method for postinitialization procedures execution.

Arguments and return defined in inherited classes. This method should be overwritten in exact application.

Remember that start() methhod is invoked after initialize()

process() - main loop iteration processing

Abstract method for main loop iteration procedures execution.

Arguments and return defined in inherited classes.

This method should be overwritten in exact application.

stop() - post processing method

This method should be rewritten in target class to contain real post processing routines.

main_loop() - main loop algorithm

This method provide default main loop alghorythm implementation and may be rewritten for alternative logic.

LOGGING AND ERROR HANDLING

log($level, $message) - write message to log

This method provides ablity to write log messages to syslog.

Example:

        $this->log("info", "New message arrived with id=$msg_id");

error($message) - return error with logging

This method extends inherited method functionality with automatically logging this message to syslog.

Example:

        if (!$dbh->ping) {
                return $this->error("We have problem with DBMS");
        }

speak(@strs) - verbose output

Paramters: list of strings to be written as verbose output

This method implements verbose output to STDOUT.

        $this->speak("Do something");

config_file($file_name) - determine full configuration file name

EXAMPLES

See samples/app.pl

BUGS

This module is a one bug itself :-)

SEE ALSO

NetSDS, NetSDS::Class::Abstract, NetSDS::Logger

TODO

Fix and cleanup!

AUTHOR

Valentyn Solomko <val@pere.org.ua>

Michael Bochkaryov <misha@rattler.kiev.ua>