Commit 62b02d49 authored by Yadd's avatar Yadd
Browse files

LEMONLDAP::NG : Doxygen documentation in progress

parent cef50ff7
......@@ -665,7 +665,7 @@ STRIP_CODE_COMMENTS = YES
# then for each documented function all documented
# functions referencing it will be listed.
REFERENCED_BY_RELATION = NO
REFERENCED_BY_RELATION = YES
# If the REFERENCES_RELATION tag is set to YES
# then for each documented function all documented entities
......
......@@ -141,12 +141,24 @@ sub more {
}
my @order = (
'Public Initialization Methods',
'Public Initialization Functions',
'Public Running Methods',
'Public Running Functions',
'Public Class Methods',
'Public Object Methods',
'Public Functions',
'Protected Initialization Methods',
'Protected Initialization Functions',
'Protected Running Methods',
'Protected Running Functions',
'Protected Class Methods',
'Protected Object Methods',
'Protected Functions',
'Private Initialization Methods',
'Private Initialization Functions',
'Private Running Methods',
'Private Running Functions',
'Private Class Methods',
'Private Object Methods',
'Private Functions',
......
......@@ -113,6 +113,24 @@ print LOG $_;
@more,
"\@nosubgrouping"
] );
} elsif ($command eq 'imethod') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
}
$args = $self->munge_parameters($args);
$self->push($self->protection($args).' Initialization Methods');
$self->start("\@fn $args")->more(@more)->end;
$self->print($args, ";\n");
$self->pop;
} elsif ($command eq 'rmethod') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
}
$args = $self->munge_parameters($args);
$self->push($self->protection($args).' Running Methods');
$self->start("\@fn $args")->more(@more)->end;
$self->print($args, ";\n");
$self->pop;
} elsif ($command eq 'cmethod') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
......@@ -122,6 +140,24 @@ print LOG $_;
$self->start("\@fn $args")->more(@more)->end;
$self->print($args, ";\n");
$self->pop;
} elsif ($command eq 'ifn') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
}
$args = $self->munge_parameters($args);
$self->push($self->protection($args).' Initialization Functions');
$self->start("\@fn $args")->more(@more)->end;
$self->print($args, ";\n");
$self->pop;
} elsif ($command eq 'rfn') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
}
$args = $self->munge_parameters($args);
$self->push($self->protection($args).' Running Functions');
$self->start("\@fn $args")->more(@more)->end;
$self->print($args, ";\n");
$self->pop;
} elsif ($command eq 'fn') {
unless ($args) {
($args) = $self->analyze_sub( $line-1 );
......@@ -169,6 +205,9 @@ print LOG $_;
if( $current_class && @args && ($args[0] eq "\$self") ) {
$self->push($self->protection($proto).' Object Methods');
$proto =~ s/\$self,*\s*//;
} elsif( $current_class && @args && ($args[0] eq "\$self") ) {
$self->push($self->protection($proto).' Initialization Methods');
$proto =~ s/\$self,*\s*//;
} elsif( $current_class
&& ((@args && ($args[0] eq "\$class")) || ($name eq "new")) ) {
$self->push($self->protection($proto).' Class Methods');
......
#!/usr/bin/perl -I.
#!/usr/bin/perl -Iscripts
eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
if 0; # not running under some shell
......
##@file
# Base package for Lemonldap::NG configuration system
##@class
# Implements Lemonldap::NG shared configuration system.
# In case of error or warning, the message is stored in the global variable
# $Lemonldap::NG::Common::Conf::msg
package Lemonldap::NG::Common::Conf;
use strict;
......@@ -13,6 +20,21 @@ our $msg;
our %_confFiles;
## @cmethod Lemonldap::NG::Common::Conf new(hashRef arg)
# Constructor.
# Succeed if it has found a way to access to Lemonldap::NG configuration with
# $arg (or default file). It can be :
# - Nothing: default configuration file is tested,
# - { File => "/path/to/storage.conf" },
# - { Type => "File", dirName => "/path/to/conf/dir/" },
# - { Type => "DBI", dbiChain => "DBI:mysql:database=lemonldap-ng;host=1.2.3.4",
# dbiUser => "user", dbiPassword => "password" },
# - { Type => "SOAP", proxy => "https://manager.example.com/soapmanager.pl" },
#
# $self->{type} contains the type of configuration access system and the
# corresponding package is loaded.
# @param $arg hash reference or hash table
# @return New Lemonldap::NG::Common::Conf object
sub new {
my $class = shift;
my $self = bless {}, $class;
......@@ -52,6 +74,10 @@ sub new {
return $self;
}
## @method private boolean _readConfFile(string file)
# Read $file to know how to access to Lemonldap::NG configuration.
# @param $file Optional file name (default: /etc/lemonldap-ng/storage.conf)
# @return True if the file was successfuly read
sub _readConfFile {
my $self = shift;
my $file = shift || DEFAULTCONFFILE;
......@@ -81,6 +107,10 @@ sub _readConfFile {
return 1;
}
## @method int saveConf(hashRef conf)
# Serialize $conf and call store().
# @param $conf Lemonldap::NG configuration hashRef
# @return Number of the saved configuration, 0 if case of error.
sub saveConf {
my ( $self, $conf ) = @_;
......@@ -115,6 +145,14 @@ sub saveConf {
return $self->store($fields);
}
## @method hashRef getConf(hashRef args)
# Get configuration from remote configuration storage system or from local
# cache if configuration has not been changed. If $args->{local} is set and if
# a local configuration is available, remote configuration is not tested.
#
# Uses lastCfg to test and getDBConf() to get the remote configuration
# @param $args Optional, contains {local=>1} or nothing
# @return Lemonldap::NG configuration
sub getConf {
my ( $self, $args ) = @_;
if ( $args->{'local'}
......@@ -139,11 +177,20 @@ sub getConf {
}
}
## @method void setLocalConf(hashRef conf)
# Store $conf in the local cache.
# @param $conf Lemonldap::NG configuration hashRef
sub setLocalConf {
my ( $self, $conf ) = @_;
$self->{refLocalStorage}->set( "conf", $conf );
}
## @method hashRef getDBConf(hashRef args)
# Get configuration from remote storage system.
# @param $args hashRef that must contains a key "cfgNum" (number of the wanted
# configuration) and optionaly a key "fields" that points to an array of wanted
# configuration keys
# @return Lemonldap::NG configuration hashRef
sub getDBConf {
my ( $self, $args ) = @_;
return undef unless $args->{cfgNum};
......@@ -198,38 +245,67 @@ sub getDBConf {
return $conf;
}
## @method boolean prereq()
# Call prereq() from the $self->{type} package.
# @return True if succeed
sub prereq {
return &{ $_[0]->{type} . '::prereq' }(@_);
}
## @method @ available()
# Call available() from the $self->{type} package.
# @return list of available configuration numbers
sub available {
return &{ $_[0]->{type} . '::available' }(@_);
}
## @method int lastCfg()
# Call lastCfg() from the $self->{type} package.
# @return Number of the last configuration available
sub lastCfg {
return &{ $_[0]->{type} . '::lastCfg' }(@_);
}
## @method boolean lock()
# Call lock() from the $self->{type} package.
# @return True if succeed
sub lock {
return &{ $_[0]->{type} . '::lock' }(@_);
}
## @method boolean isLocked()
# Call isLocked() from the $self->{type} package.
# @return True if database is locked
sub isLocked {
return &{ $_[0]->{type} . '::isLocked' }(@_);
}
## @method boolean unlock()
# Call unlock() from the $self->{type} package.
# @return True if succeed
sub unlock {
return &{ $_[0]->{type} . '::unlock' }(@_);
}
## @method int store(hashRef conf)
# Call store() from the $self->{type} package.
# @param $conf Lemondlap configuration serialized
# @return Number of new configuration stored if succeed, 0 else.
sub store {
return &{ $_[0]->{type} . '::store' }(@_);
}
## @method load(int cfgNum, arrayRef fields)
# Call load() from the $self->{type} package.
# @return Lemonldap::NG Configuration hashRef if succeed, 0 else.
sub load {
return &{ $_[0]->{type} . '::load' }(@_);
}
## @method boolean delete(int cfgNum)
# Call delete() from the $self->{type} package.
# @param $cfgNum Number of configuration to delete
# @return True if succeed
sub delete {
my ( $self, $c ) = @_;
my @a = $self->available();
......
......@@ -5,6 +5,16 @@
## @class
# Main handler.
# All methods in handler are class methods: in ModPerl environment, handlers
# are always launched without object created.
#
# The main method is run() who is called by Apache for each requests (using
# handler() wrapper).
#
# The initialization process is splitted in two parts :
# - init() is launched as Apache startup
# - globalInit() is launched at each first request received by an Apache child
# and each time a new configuration is detected
package Lemonldap::NG::Handler::SharedConf;
use strict;
......@@ -46,7 +56,7 @@ BEGIN {
# INIT PROCESS
## @cmethod void init(hashRef args)
## @imethod void init(hashRef args)
# Constructor.
# init is overloaded to call only localInit. globalInit is called later.
# @param $args hash containing parameters
......@@ -57,7 +67,7 @@ sub init($$) {
$class->localInit($args);
}
## @cmethod void defaultValuesInit(hashRef args)
## @imethod protected void defaultValuesInit(hashRef args)
# Set default values for non-customized variables
# @param $args hash containing parameters
# @return boolean
......@@ -69,7 +79,7 @@ sub defaultValuesInit {
return $class->SUPER::defaultValuesInit( \%h );
}
## @cmethod void localInit(hashRef args)
## @imethod void localInit(hashRef args)
# Load parameters and build the Lemonldap::NG::Common::Conf object.
# @return boolean
sub localInit {
......@@ -88,7 +98,7 @@ sub localInit {
# MAIN
## @cmethod int run(Apache2::RequestRec r)
## @rmethod int run(Apache2::RequestRec r)
# Check configuration and launch Lemonldap::NG::Handler::Simple::run().
# Each $reloadTime, the Apache child verify if its configuration is the same
# as the configuration stored in the local storage.
......@@ -107,7 +117,7 @@ sub run($$) {
# CONFIGURATION UPDATE
## @cmethod int testConf(boolean local)
## @rmethod protected int testConf(boolean local)
# Test if configuration has changed and launch setConf() if needed.
# If the optional boolean $local is true, remote configuration is not tested:
# only local cached configuration is tested if available. $local is given to
......@@ -131,7 +141,7 @@ sub testConf {
OK;
}
## @cmethod int setConf(hashRef conf)
## @rmethod protected int setConf(hashRef conf)
# Launch globalInit().
# Local parameters have best precedence on configuration parameters.
# @return Apache constant
......@@ -149,10 +159,12 @@ sub setConf {
*reload = *refresh;
## @cmethod int refresh(Apache::RequestRec r)
## @rmethod int refresh(Apache::RequestRec r)
# Launch testConf() with $local=0, so remote configuration is tested.
# Then build a simple HTTP response that just returns "200 OK" or
# "500 Server Error".
# @param $r current request
# @return Apache constant
# @return Apache constant (OK or SERVER_ERROR)
sub refresh($$) {
my ( $class, $r ) = @_;
$class->lmLog( "$class: request for configuration reload", 'notice' );
......
......@@ -4,7 +4,15 @@
# @copy 2005, 2006, 2007, 2008 Xavier Guimard <x.guimard@free.fr>
## @class
# Base class for Lemonldap::NG handlers
# Base class for Lemonldap::NG handlers.
# All methods in handler are class methods: in ModPerl environment, handlers
# are always launched without object created.
#
# The main method is run() who is called by Apache for each requests (using
# handler() wrapper).
#
# The main initialization subroutine is init() who launch localInit() and
# globalInit().
package Lemonldap::NG::Handler::Simple;
use strict;
......@@ -142,31 +150,31 @@ BEGIN {
*logout = ( MP() == 2 ) ? \&logout_mp2 : \&logout_mp1;
}
## @cmethod int handler_mp1()
## @rmethod protected int handler_mp1()
# Launch run() when used under mod_perl version 1
# @return Apache constant
sub handler_mp1 ($$) { shift->run(@_); }
## @cmethod int handler_mp2()
## @rmethod protected int handler_mp2()
# Launch run() when used under mod_perl version 2
# @return Apache constant
sub handler_mp2 : method {
shift->run(@_);
}
## @cmethod int logout_mp1()
## @rmethod protected int logout_mp1()
# Launch unlog() when used under mod_perl version 1
# @return Apache constant
sub logout_mp1 ($$) { shift->unlog(@_); }
## @cmethod int logout_mp2()
## @rmethod protected int logout_mp2()
# Launch unlog() when used under mod_perl version 2
# @return Apache constant
sub logout_mp2 : method {
shift->unlog(@_);
}
## @cmethod void lmLog(string mess, string level)
## @rmethod void lmLog(string mess, string level)
# Wrapper for Apache log system
# @param $mess message to log
# @param $level string (debug, info, warning or error)
......@@ -183,7 +191,7 @@ sub lmLog {
}
}
## @fn void lmSetApacheUser(Apache2::RequestRec r,string s)
## @rfn protected void lmSetApacheUser(Apache2::RequestRec r,string s)
# Inform Apache for the data to use as user for logs
# @param $r current request
# @param $s string to use
......@@ -193,7 +201,7 @@ sub lmSetApacheUser {
$r->connection->user($s);
}
## @fn string protected regRemoteIp(string str)
## @ifn protected string protected regRemoteIp(string str)
# Replaces $ip by the client IP address in the string
# @param $str string
# @return string
......@@ -208,7 +216,7 @@ sub regRemoteIp {
return $str;
}
## @fn void lmSetHeaderIn(Apache2::RequestRec r, string h, string v)
## @rfn void lmSetHeaderIn(Apache2::RequestRec r, string h, string v)
# Set an HTTP header in the HTTP request.
# @param $r Current request
# @param $h Name of the header
......@@ -223,7 +231,7 @@ sub lmSetHeaderIn {
}
}
## @fn string lmtHeaderIn(Apache2::RequestRec r, string h)
## @rfn string lmtHeaderIn(Apache2::RequestRec r, string h)
# Return an HTTP header value from the HTTP request.
# @param $r Current request
# @param $h Name of the header
......@@ -238,7 +246,7 @@ sub lmHeaderIn {
}
}
## @fn void lmSetErrHeaderOut(Apache2::RequestRec r, string h, string v)
## @rfn void lmSetErrHeaderOut(Apache2::RequestRec r, string h, string v)
# Set an HTTP header in the HTTP response in error context
# @param $r Current request
# @param $h Name of the header
......@@ -253,7 +261,7 @@ sub lmSetErrHeaderOut {
}
}
## @fn void lmSetHeaderOut(Apache2::RequestRec r, string h, string v)
## @rfn void lmSetHeaderOut(Apache2::RequestRec r, string h, string v)
# Set an HTTP header in the HTTP response in normal context
# @param $r Current request
# @param $h Name of the header
......@@ -268,7 +276,7 @@ sub lmSetHeaderOut {
}
}
## @fn string lmtHeaderOut(Apache2::RequestRec r, string h)
## @rfn string lmtHeaderOut(Apache2::RequestRec r, string h)
# Return an HTTP header value from the HTTP response.
# @param $r Current request
# @param $h Name of the header
......@@ -285,7 +293,7 @@ sub lmHeaderOut {
# Status daemon creation
## @fn void statusProcess()
## @ifn protected void statusProcess()
# Launch the status processus.
sub statusProcess {
require IO::Pipe;
......@@ -319,7 +327,7 @@ sub statusProcess {
# Initialization subroutines #
##############################
## @cmethod Safe safe()
## @imethod protected Safe safe()
# Build and return the security jail used to compile rules and headers.
# @return Safe object
sub safe {
......@@ -348,7 +356,7 @@ sub safe {
return $safe;
}
## @cmethod void init(hashRef args)
## @imethod void init(hashRef args)
# Calls localInit() and globalInit().
# @param $args reference to the initialization hash
sub init($$) {
......@@ -357,7 +365,7 @@ sub init($$) {
$class->globalInit(@_);
}
## @cmethod void localInit(hashRef args)
## @imethod void localInit(hashRef args)
# Call purgeCache() to purge the local cache, launch the status process
# (statusProcess()) in wanted and launch childInit().
# @param $args reference to the initialization hash
......@@ -375,7 +383,7 @@ sub localInit($$) {
$class->childInit();
}
## @cmethod boolean childInit()
## @imethod protected boolean childInit()
# Indicates to Apache that it has to launch:
# - initLocalStorage() for each child process (after uid change)
# - cleanLocalStorage() after each requests
......@@ -408,7 +416,7 @@ sub childInit {
1;
}
## @cmethod void purgeCache()
## @imethod protected void purgeCache()
# Purge the local cache.
# Launched at Apache startup.
sub purgeCache {
......@@ -429,7 +437,7 @@ sub purgeCache {
}
}
## @cmethod void globalInit(hashRef args)
## @imethod void globalInit(hashRef args)
# Global initialization process. Launch :
# - locationRulesInit()
# - defaultValuesInit()
......@@ -446,7 +454,7 @@ sub globalInit {
$class->forgeHeadersInit(@_);
}
## @cmethod void locationRulesInit(hashRef args)
## @imethod protected void locationRulesInit(hashRef args)
# Compile rules.
# Rules are stored in $args->{locationRules} that contains regexp=>test
# expressions where :
......@@ -481,7 +489,7 @@ sub locationRulesInit {
1;
}
## @cmethod codeRef conditionSub(string cond)
## @imethod protected codeRef conditionSub(string cond)
# Returns a compiled function used to grant users (used by
# locationRulesInit().
# @param $cond The boolean expression to use
......@@ -534,7 +542,7 @@ sub conditionSub {
return $sub;
}
## @cmethod void defaultValuesInit(hashRef args)
## @imethod protected void defaultValuesInit(hashRef args)
# Set default values for non-customized variables
# @param $args reference to the configuration hash
sub defaultValuesInit {
......@@ -552,7 +560,7 @@ sub defaultValuesInit {
1;
}
## @cmethod void portalInit(hashRef args)
## @imethod protected void portalInit(hashRef args)
# Verify that portal variable exists. Die unless
# @param $args reference to the configuration hash
sub portalInit {
......@@ -560,7 +568,7 @@ sub portalInit {
$portal = $args->{portal} or die("portal parameter required");
}
## @cmethod void globalStorageInit(hashRef args)
## @imethod protected void globalStorageInit(hashRef args)
# Initialize the Apache::Session::* module choosed to share user's variables.
# @param $args reference to the configuration hash
sub globalStorageInit {
......@@ -571,7 +579,7 @@ sub globalStorageInit {
$globalStorageOptions = $args->{globalStorageOptions};
}
## @cmethod void forgeHeadersInit(hashRef args)
## @imethod protected void forgeHeadersInit(hashRef args)
# Create the &$forgeHeaders subroutine used to insert
# headers into the HTTP request.
# @param $args reference to the configuration hash
......@@ -603,7 +611,24 @@ sub forgeHeadersInit {
1;
}
## @cmethod void updateStatus(string user,string url,string action)
## @imethod protected int initLocalStorage()
# Prepare local cache (if not done before by Lemonldap::NG::Common::Conf)
# @return Apache2::Const::DECLINED
sub initLocalStorage {
my ( $class, $r ) = @_;
if ( $localStorage and not $refLocalStorage ) {
eval "use $localStorage;\$refLocalStorage = new $localStorage(\$localStorageOptions);";
$class->lmLog( "Local cache initialization failed: $@", 'error' )
unless ( defined $refLocalStorage );
}
return DECLINED;
}
###################
# RUNNING METHODS #
###################
## @rmethod protected void updateStatus(string user,string url,string action)
# Inform the status process of the result of the request if it is available.
sub updateStatus {
my ( $class, $user, $url, $action ) = @_;
......@@ -615,11 +640,7 @@ sub updateStatus {
};
}
###################
# RUNNING METHODS #
###################
## @cmethod boolean grant()
## @rmethod protected boolean grant()
# Grant or refuse client using compiled regexp and functions
# @return True if the user is granted to access to the current URL
sub grant {
......@@ -631,7 +652,7 @@ sub grant {
return &$defaultCondition($datas);
}
## @cmethod int forbidden()
## @rmethod protected int forbidden()
# Used to reject non authorizated requests.
# Inform the status processus and call logForbidden().
# @return Apache2::Const::FORBIDDEN
......@@ -648,7 +669,7 @@ sub forbidden {
return FORBIDDEN;
}
## @cmethod void logForbidden()