| NetSDS::App(3pm) | User Contributed Perl Documentation | NetSDS::App(3pm) |
NetSDS::App - common application superclass
#!/usr/bin/env perl
use 5.8.0;
use warnings;
use strict;
MyApp->run(
conf_file => '/etc/NetSDS/myapp.conf', # default place for config search
daemon => 1, # run in daemon mode
use_pidfile => 1, # write PID file to avoid double processing
verbose => 0, # no verbosity
);
1;
# Application logic here
package MyApp;
use base 'NetSDS::App';
# Startup hook
sub start {
my ($self) = @_;
# Use configuration
$self->{listen_port} = $self->conf->{listen_port};
# Use logging subsystem
$self->log("info", "Application successfully started with PID=".$self->pid);
}
# Main processing hook
sub process {
my ($self) = @_;
print "Hello!";
# Use verbose output
$self->speak("Trying to be more verbose");
}
"NetSDS::App" is a base class for NetSDS applications. It implements common functionality including the following:
* initialization
* configuration file processing
* command line parameters processing
* application workflow
* daemonization
* PID file processing
* logging
* event detail records writing
* default signal handling
New application should be inherited from "NetSDS::App" class directly or via child classes for more specific tasks like CGI, AGI, SMPP and other.
Common application workflow is described on this diagram:
App->run(%params)
|
initialize()
|
----------
| |
start() |
| |
process() --- main_loop()
| |
stop() |
| |
----------
|
finalize()
When application is starting "initialize()" method is invoked first. It provides common start time functionality like CLI parameters processing, daemonization, reading configuration.
"initialize()" method may be overwritten in more specific frameworks to change default behaviour of some application types.
Then "main_loop()" method invoked to process main application logic. This method provides three redefinable hooks: "start()", "process()" and "stop()". Theese hooks should be overwritten to implement necessary logic.
Depending on "infinite" flag main_loop() may call process() hook in infinite loop or only once.
"main_loop()" workflow may be redefined in inherited framework to implement some other process flow logic.
On the last step "finalize()" method is invoked to make necessary finalization actions on framework level.
Application class may be provided with a number of parameters that allows to manage application behaviour. For example it may be a configuration file, daemonization mode or debugging flag.
Such parameters are passed to run() method as hash:
MyApp->run(
has_conf => 1,
conf_file => '/etc/sample/file.conf',
daemon => 1,
use_pidfile => 1,
);
Mostly our applications requires configuration files but some of them doesn't require any configuration (e.g. small utilities, etc). Set "has_conf" parameter to 0 to avoid search of configuration file.
This parameter allows to set explicitly path to configuration file. By default it's determined from application name and is looking like "/etc/NetSDS/{name}.conf"
This name is used for config and PID file names, logging. By default it's automatically detected by executable script name.
This parameter should be set to 1 if you plan to use automatically plugged application features. Read "PLUGGABLE APPLICATION FEATURES" section below.
Command line parameters may be passed to NetSDS application to override defaults.
These CLI options overrides "conf_file", "debug", "daemon", "verbose" and "name" default parameters that are passed in run() method.
Examples:
# Debugging in foreground mode
./application --config=/etc/myapp.conf --nodaemon --debug
# Set application name explicitly
./application --name=myapp
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
All method parameters are transparently passed to application constructor.
#!/usr/bin/env perl
use 5.8.0;
use warnings;
use strict;
MyApp->run(
conf_file => '/etc/myapp.conf',
daemon => 1,
use_pidfile => 1,
);
1;
# **********************************
# Logic of application
package MyApp;
use base 'NetSDS::App';
1;
print "My name is " . $self->name;
print "My PID is " . $self->pid;
if ($self->debug) {
print "Debug info: " . $debug_data;
}
It may be used to increase application verbosity level if necessary.
if ($self->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.
NOTE: There is no need to use this method directly in application. See "log()" method description to understand logging features.
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 = $self->conf->{content_dir};
my $kannel_url = $self->conf->{kannel}->{send_url};
$app->pid_dir("/var/run");
if ($self->daemon()) {
$self->log("info", "Yeah! I'm daemon!");
};
# Switch to infinite loop mode
$app->infinite(1);
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.
Returns: feature object
$self->add_feature('kannel','NetSDS::Feature::Kannel', $self->conf->{feature}->{kannel});
$self->kannel->send(.....);
Arguments and return defined in inherited classes. This method should be overwritten in exact application.
Remember that start() methhod is invoked after initialize()
Arguments and return defined in inherited classes.
This method should be overwritten in exact application.
Example:
$self->log("info", "New message arrived with id=$msg_id");
Example:
if (!$dbh->ping) {
return $self->error("We have problem with DBMS");
}
This method implements verbose output to STDOUT.
$self->speak("Do something");
$app->edr({
event => "call",
status => "rejected",
});
To add more flexibility to application development "NetSDS::App" framework allows to add pluggable features. Application feature is a class dynamically loaded into application using configuration file parameters.
To use application features developer should do the following:
* set auto_features run() parameter
* create "feature" sections in application as described
* create feature classes inherited from NetSDS::Feature
See samples/app.pl
This module is a one bug itself :-)
NetSDS, NetSDS::Class::Abstract, NetSDS::Logger
Fix and cleanup!
Valentyn Solomko <val@pere.org.ua>
Michael Bochkaryov <misha@rattler.kiev.ua>
Copyright (C) 2008-2009 Net Style Ltd.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
| 2015-06-11 | perl v5.20.2 |