.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NetSDS::App 3pm"
.TH NetSDS::App 3pm "2021-12-26" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
NetSDS::App \- common application superclass
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #!/usr/bin/env perl
\&
\& use 5.8.0;
\& use warnings;
\& use strict;
\&
\& MyApp\->run(
\& conf_file => \*(Aq/etc/NetSDS/myapp.conf\*(Aq, # 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 \*(AqNetSDS::App\*(Aq;
\&
\& # 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");
\&
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`NetSDS::App\*(C'\fR is a base class for NetSDS applications.
It implements common functionality including the following:
.PP
.Vb 9
\& * initialization
\& * configuration file processing
\& * command line parameters processing
\& * application workflow
\& * daemonization
\& * PID file processing
\& * logging
\& * event detail records writing
\& * default signal handling
.Ve
.PP
New application should be inherited from \f(CW\*(C`NetSDS::App\*(C'\fR class
directly or via child classes for more specific tasks like
\&\s-1CGI, AGI, SMPP\s0 and other.
.PP
Common application workflow is described on this diagram:
.PP
.Vb 10
\& App\->run(%params)
\& |
\& initialize()
\& |
\& \-\-\-\-\-\-\-\-\-\-
\& | |
\& start() |
\& | |
\& process() \-\-\- main_loop()
\& | |
\& stop() |
\& | |
\& \-\-\-\-\-\-\-\-\-\-
\& |
\& finalize()
.Ve
.PP
When application is starting \f(CW\*(C`initialize()\*(C'\fR method is invoked first.
It provides common start time functionality like \s-1CLI\s0 parameters processing,
daemonization, reading configuration.
.PP
\&\f(CW\*(C`initialize()\*(C'\fR method may be overwritten in more specific frameworks
to change default behaviour of some application types.
.PP
Then \f(CW\*(C`main_loop()\*(C'\fR method invoked to process main application logic.
This method provides three redefinable hooks: \f(CW\*(C`start()\*(C'\fR, \f(CW\*(C`process()\*(C'\fR and \f(CW\*(C`stop()\*(C'\fR.
Theese hooks should be overwritten to implement necessary logic.
.IP "\(bu" 4
\&\fB\fBstart()\fB\fR \- start time hook
.IP "\(bu" 4
\&\fB\fBprocess()\fB\fR \- process iteration hook
.IP "\(bu" 4
\&\fB\fBstop()\fB\fR \- finish time hook
.PP
Depending on \f(CW\*(C`infinite\*(C'\fR flag \fBmain_loop()\fR may call \fBprocess()\fR hook
in infinite loop or only once.
.PP
\&\f(CW\*(C`main_loop()\*(C'\fR workflow may be redefined in inherited framework to implement
some other process flow logic.
.PP
On the last step \f(CW\*(C`finalize()\*(C'\fR method is invoked to make necessary
finalization actions on framework level.
.SH "STARTUP PARAMETERS"
.IX Header "STARTUP PARAMETERS"
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.
.PP
Such parameters are passed to \fBrun()\fR method as hash:
.PP
.Vb 6
\& MyApp\->run(
\& has_conf => 1,
\& conf_file => \*(Aq/etc/sample/file.conf\*(Aq,
\& daemon => 1,
\& use_pidfile => 1,
\& );
.Ve
.IP "\(bu" 4
\&\fBhas_conf\fR \- 1 if configuration file is required (default: yes)
.Sp
Mostly our applications requires configuration files but some of them
doesn't require any configuration (e.g. small utilities, etc).
Set \f(CW\*(C`has_conf\*(C'\fR parameter to 0 to avoid search of configuration file.
.IP "\(bu" 4
\&\fBconf_file\fR \- default path to configuration file (default: autodetect)
.Sp
This parameter allows to set explicitly path to configuration file.
By default it's determined from application name and is looking like
\&\f(CW\*(C`/etc/NetSDS/{name}.conf\*(C'\fR
.IP "\(bu" 4
\&\fBname\fR \- application name (default: autodetect)
.Sp
This name is used for config and \s-1PID\s0 file names, logging.
By default it's automatically detected by executable script name.
.IP "\(bu" 4
\&\fBdebug\fR \- 1 for debugging flag (default: no)
.IP "\(bu" 4
\&\fBdaemon\fR \- 1 for daemon mode (default: no)
.IP "\(bu" 4
\&\fBverbose\fR \- 1 for verbose mode (default: no)
.IP "\(bu" 4
\&\fBuse_pidfile\fR \- 1 to use \s-1PID\s0 files (default: no)
.IP "\(bu" 4
\&\fBpid_dir\fR \- path to \s-1PID\s0 files catalog (default: '/var/run/NetSDS')
.IP "\(bu" 4
\&\fBauto_features\fR \- 1 for auto features inclusion (default: no)
.Sp
This parameter should be set to 1 if you plan to use automatically plugged
application features. Read \f(CW\*(C`PLUGGABLE APPLICATION FEATURES\*(C'\fR section below.
.IP "\(bu" 4
\&\fBinfinite\fR \- 1 for inifinite loop (default: yes)
.IP "\(bu" 4
\&\fBedr_file\fR \- \s-1EDR\s0 (event detail records) file name (default: undef)
.SH "COMMAND LINE PARAMETERS"
.IX Header "COMMAND LINE PARAMETERS"
Command line parameters may be passed to NetSDS application to override defaults.
.IP "\(bu" 4
\&\fB\-\-conf\fR \- path to config file
.IP "\(bu" 4
\&\fB\-\-[no]debug\fR \- set debug mode
.IP "\(bu" 4
\&\fB\-\-[no]daemon\fR \- set daemon/foreground mode
.IP "\(bu" 4
\&\fB\-\-[no]verbose\fR \- set verbosity mode
.IP "\(bu" 4
\&\fB\-\-name\fR \- set application name
.PP
These \s-1CLI\s0 options overrides \f(CW\*(C`conf_file\*(C'\fR, \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`daemon\*(C'\fR, \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`name\*(C'\fR default parameters
that are passed in \fBrun()\fR method.
.PP
Examples:
.PP
.Vb 2
\& # Debugging in foreground mode
\& ./application \-\-config=/etc/myapp.conf \-\-nodaemon \-\-debug
\&
\& # Set application name explicitly
\& ./application \-\-name=myapp
.Ve
.SH "CLASS API"
.IX Header "CLASS API"
.IP "\fBnew([%params])\fR \- class constructor" 4
.IX Item "new([%params]) - class constructor"
Constructor is usually invoked from \f(CW\*(C`run()\*(C'\fR class method.
It creates application object and set its initial properties
from oarameters passed as hash.
.Sp
Standard parameters are:
.Sp
.Vb 10
\& * 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
.Ve
.IP "\fBrun(%parameters)\fR \- application launcher" 4
.IX Item "run(%parameters) - application launcher"
This method calls class constructor and then switch to \f(CW\*(C`main_loop()\*(C'\fR method.
.Sp
All method parameters are transparently passed to application constructor.
.Sp
.Vb 1
\& #!/usr/bin/env perl
\&
\& use 5.8.0;
\& use warnings;
\& use strict;
\&
\& MyApp\->run(
\& conf_file => \*(Aq/etc/myapp.conf\*(Aq,
\& daemon => 1,
\& use_pidfile => 1,
\& );
\&
\& 1;
\&
\& # **********************************
\& # Logic of application
\&
\& package MyApp;
\& use base \*(AqNetSDS::App\*(Aq;
\& 1;
.Ve
.IP "\fBname([$name])\fR \- application name" 4
.IX Item "name([$name]) - application name"
This method is an accessor to application name allowing to retrieve
this or set new one.
.Sp
.Vb 1
\& print "My name is " . $self\->name;
.Ve
.IP "\fB\fBpid()\fB\fR \- \s-1PID\s0 of application process" 4
.IX Item "pid() - PID of application process"
Read only access to process identifier (\s-1PID\s0).
.Sp
.Vb 1
\& print "My PID is " . $self\->pid;
.Ve
.IP "\fB\fBdebug()\fB\fR \- debugging flag" 4
.IX Item "debug() - debugging flag"
This method provides an accessor to debugging flag.
If application called with \-\-debug option it will return \s-1TRUE\s0 value.
.Sp
.Vb 3
\& if ($self\->debug) {
\& print "Debug info: " . $debug_data;
\& }
.Ve
.IP "\fB\fBverbose()\fB\fR \- verbosity flag" 4
.IX Item "verbose() - verbosity flag"
This method provides an accessor to verbosity flag.
.Sp
It may be used to increase application verbosity level if necessary.
.Sp
.Vb 3
\& if ($self\->verbose) {
\& print "I\*(Aqm working!";
\& };
.Ve
.Sp
\&\s-1NOTE:\s0 This flag is is for normal operations. If you need implement debug
output or other development/testing functionality \- use \fBdebug()\fR instead.
.IP "\fB\fBlogger()\fB\fR \- accessor to logger" 4
.IX Item "logger() - accessor to logger"
This method is accessor to logger (object of NetSDS::Logger class).
.Sp
\&\s-1NOTE:\s0 There is no need to use this method directly in application. See \f(CW\*(C`log()\*(C'\fR
method description to understand logging features.
.IP "\fB\fBconf()\fB\fR \- accessor to configuration" 4
.IX Item "conf() - accessor to configuration"
This method is accessor to application configuration represented as
hash reference returned by NetSDS::Conf module.
.Sp
Configuration sample:
.Sp
.Vb 2
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& content_dir /var/lib/content
\&
\&
\& send_url http://127.0.0.1:13013/
\& login netsds
\& passwd topsecret
\&
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.Ve
.Sp
Code sample:
.Sp
.Vb 3
\& # Retrieve configuration
\& my $content_dir = $self\->conf\->{content_dir};
\& my $kannel_url = $self\->conf\->{kannel}\->{send_url};
.Ve
.IP "\fBuse_pidfile(\s-1BOOL\s0)\fR \- \s-1PID\s0 file checking flag" 4
.IX Item "use_pidfile(BOOL) - PID file checking flag"
Paramters: \s-1TRUE\s0 if \s-1PID\s0 file checking required
.IP "\fBpid_dir([$directory])\fR \- \s-1PID\s0 files storage" 4
.IX Item "pid_dir([$directory]) - PID files storage"
Paramters: directory name
.Sp
.Vb 1
\& $app\->pid_dir("/var/run");
.Ve
.IP "\fBdaemon(\s-1BOOL\s0)\fR \- daemonization flag" 4
.IX Item "daemon(BOOL) - daemonization flag"
Paramters: \s-1TRUE\s0 if application should be a daemon
.Sp
.Vb 3
\& if ($self\->daemon()) {
\& $self\->log("info", "Yeah! I\*(Aqm daemon!");
\& };
.Ve
.IP "\fB\fBauto_features()\fB\fR \- auto features flag" 4
.IX Item "auto_features() - auto features flag"
Automatic features inclusion allowed if \s-1TRUE.\s0
.IP "\fBinfinite([$bool])\fR \- is application in infinite loop" 4
.IX Item "infinite([$bool]) - is application in infinite loop"
Example:
.Sp
.Vb 2
\& # Switch to infinite loop mode
\& $app\->infinite(1);
.Ve
.IP "\fBedr_file([$file_name])\fR \- accessor to \s-1EDR\s0 file name" 4
.IX Item "edr_file([$file_name]) - accessor to EDR file name"
Paramters: \s-1EDR\s0 file path
.IP "\fB\fBinitialize()\fB\fR" 4
.IX Item "initialize()"
Common application initialization:
.Sp
1. Reading config if necessary.
.Sp
2. Daemonize application.
.Sp
3. Check \s-1PID\s0 file for already running application instances.
.Sp
4. Start logger.
.Sp
5. Prepare default signal handlers.
.IP "\fB\fBuse_auto_features()\fB\fR \- add features to application" 4
.IX Item "use_auto_features() - add features to application"
This method implements automatic features inclusion by application
configuration file (see \f(CW\*(C`feature\*(C'\fR sections).
.IP "\fBadd_feature($name, \f(CB$class\fB, \f(CB$config\fB, \f(CB%params\fB)\fR \- add feature" 4
.IX Item "add_feature($name, $class, $config, %params) - add feature"
Paramters: feature name, class name, parameters (optional)
.Sp
Returns: feature object
.Sp
.Vb 2
\& $self\->add_feature(\*(Aqkannel\*(Aq,\*(AqNetSDS::Feature::Kannel\*(Aq, $self\->conf\->{feature}\->{kannel});
\& $self\->kannel\->send(.....);
.Ve
.IP "\fB\fBfinalize()\fB\fR \- switch to finalization stage" 4
.IX Item "finalize() - switch to finalization stage"
This method called if we need to finish application.
.IP "\fB\fBstart()\fB\fR \- user defined initialization hook" 4
.IX Item "start() - user defined initialization hook"
Abstract method for postinitialization procedures execution.
.Sp
Arguments and return defined in inherited classes.
This method should be overwritten in exact application.
.Sp
Remember that \fBstart()\fR methhod is invoked after \fBinitialize()\fR
.IP "\fB\fBprocess()\fB\fR \- main loop iteration hook" 4
.IX Item "process() - main loop iteration hook"
Abstract method for main loop iteration procedures execution.
.Sp
Arguments and return defined in inherited classes.
.Sp
This method should be overwritten in exact application.
.IP "\fB\fBstop()\fB\fR \- post processing hook" 4
.IX Item "stop() - post processing hook"
This method should be rewritten in target class to contain real
post processing routines.
.IP "\fB\fBmain_loop()\fB\fR \- main loop algorithm" 4
.IX Item "main_loop() - main loop algorithm"
This method provide default main loop alghorythm implementation and may
be rewritten for alternative logic.
.SH "LOGGING AND ERROR HANDLING"
.IX Header "LOGGING AND ERROR HANDLING"
.IP "\fBlog($level, \f(CB$message\fB)\fR \- write message to log" 4
.IX Item "log($level, $message) - write message to log"
This method provides ablity to write log messages to syslog.
.Sp
Example:
.Sp
.Vb 1
\& $self\->log("info", "New message arrived with id=$msg_id");
.Ve
.IP "\fBerror($message)\fR \- return error with logging" 4
.IX Item "error($message) - return error with logging"
This method extends inherited method functionality with automatically
logging this message to syslog.
.Sp
Example:
.Sp
.Vb 3
\& if (!$dbh\->ping) {
\& return $self\->error("We have problem with DBMS");
\& }
.Ve
.IP "\fBspeak(@strs)\fR \- verbose output" 4
.IX Item "speak(@strs) - verbose output"
Paramters: list of strings to be written as verbose output
.Sp
This method implements verbose output to \s-1STDOUT.\s0
.Sp
.Vb 1
\& $self\->speak("Do something");
.Ve
.IP "\fBedr($record [,$record..])\fR \- write \s-1EDR\s0" 4
.IX Item "edr($record [,$record..]) - write EDR"
Paramters: list of \s-1EDR\s0 records to write
.Sp
.Vb 4
\& $app\->edr({
\& event => "call",
\& status => "rejected",
\& });
.Ve
.IP "\fBconfig_file($file_name)\fR \- determine full configuration file name" 4
.IX Item "config_file($file_name) - determine full configuration file name"
.SH "PLUGGABLE APPLICATION FEAUTURES"
.IX Header "PLUGGABLE APPLICATION FEAUTURES"
To add more flexibility to application development \f(CW\*(C`NetSDS::App\*(C'\fR framework allows to add pluggable features.
Application feature is a class dynamically loaded into application using configuration file parameters.
.PP
To use application features developer should do the following:
.PP
* set auto_features \fBrun()\fR parameter
.PP
* create \f(CW\*(C`feature\*(C'\fR sections in application as described
.PP
* create feature classes inherited from NetSDS::Feature
.SH "EXAMPLES"
.IX Header "EXAMPLES"
See samples/app.pl
.SH "BUGS"
.IX Header "BUGS"
This module is a one bug itself :\-)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
NetSDS, NetSDS::Class::Abstract, NetSDS::Logger
.SH "TODO"
.IX Header "TODO"
Fix and cleanup!
.SH "AUTHOR"
.IX Header "AUTHOR"
Valentyn Solomko
.PP
Michael Bochkaryov
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) 2008\-2009 Net Style Ltd.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA\s0