[vhffs-dev] [2010] reworked Vhffs::Main

[subversion@xxxxxxxxxxxxx]

Revision: 2010
Author:   gradator
Date:     2012-02-16 01:06:27 +0100 (Thu, 16 Feb 2012)
Log Message:
-----------
reworked Vhffs::Main

Modified Paths:
--------------
    trunk/vhffs-api/src/Vhffs/Main.pm

Modified: trunk/vhffs-api/src/Vhffs/Main.pm
===================================================================
--- trunk/vhffs-api/src/Vhffs/Main.pm	2012-02-15 21:39:36 UTC (rev 2009)
+++ trunk/vhffs-api/src/Vhffs/Main.pm	2012-02-16 00:06:27 UTC (rev 2010)
@@ -30,7 +30,6 @@
 
 package Vhffs::Main;
 
-
 use strict;
 use utf8;
 use DBI;
@@ -38,11 +37,37 @@
 use Vhffs::Functions;
 use Vhffs::Conf;
 
+=pod
+=head1 NAME
+
+Vhffs::Main - The Main class of Vhffs API, Config file access and Backend access
+
+=head1 SYNOPSIS
+
+	use Vhffs::Main;
+	my $vhffs = init Vhffs::Main or die();
+	my $conf = $vhffs->get_config;
+
+=head1 DESCRIPTION
+
+The Vhffs::Main object is the main Vhffs class. When you
+invoke init Vhffs::Main, it creates a Vhffs::Main object that read configuration
+and create a Vhffs::Conf object then create by default a connection to backend.
+
+=head1 METHODS
+=cut
+
+=pod
+
+=head1 init( \%opts )
+
+my $vhffs = init Vhffs::Main( { backend => 1 } ) or die();
+
+=cut
 sub init {
-
 	my $class = ref( $_[0] ) || $_[0];
 	my $opt = $_[1];
- 
+
 	# First, config stuff
 	my $config = new Vhffs::Conf( Vhffs::Constants::CONF_PATH );
 	return undef unless defined $config;
@@ -62,42 +87,46 @@
 	return $self;
 }
 
-sub get_db_object {
+=pod
 
-	my $self = shift;
+=head1 get_db_object
 
-	if( defined $self->{'db'} )
-	{
-		return $self->{'db'};
-	}
-	else
-	{
-		return undef;
-	}
-}
+my $dbh = $vhffs->get_db_object;
 
-sub get_config {
+Returns a C<DBI> object if backend was connected, otherwise returns undef.
 
+=cut
+sub get_db_object {
 	my $self = shift;
-
-	if( defined $self->{'config'} )
-	{
-		return $self->{'config'};
-	}
-	else
-	{
-		return undef;
-	}
+	return $self->{'db'};
 }
 
-sub is_connected {
+=pod
 
-    my $self = shift;
-    return (defined $self->{db} and $self->{db}->ping() > 0);
+=head1 get_config
+
+my $config = $vhffs->get_cofig;
+
+Returns a C<Vhffs::Conf> object.
+
+=cut
+sub get_config {
+	my $self = shift;
+	return $self->{'config'};
 }
 
+=pod
+
+=head1 connect
+
+my $dbh = $vhffs->connect;
+
+Connect to backend, should only be used once, and only if backend was set to false in constructor options.
+
+Returns a C<DBI> object if connection succeded, otherwise returns undef.
+
+=cut
 sub connect {
-
 	my $self = shift;
 	my $config = $self->{config}->get_database();
 
@@ -121,15 +150,47 @@
 	return undef;
 }
 
-sub reconnect {
+=pod
 
+=head1 is_connected
+
+my $connected = $vhffs->is_connected;
+
+Returns true if backend connection is alive, otherwise return false.
+
+=cut
+sub is_connected {
 	my $self = shift;
+	return (defined $self->{db} and $self->{db}->ping() > 0);
+}
+
+=pod
+
+=head1 reconnect
+
+my $dbh = $vhffs->reconnect;
+
+Reconnect to the database if necessary.
+
+Returns a C<DBI> object if everything went fine, otherwise returns undef.
+
+=cut
+sub reconnect {
+	my $self = shift;
 	return $self->{db} if defined $self->{db} and $self->{db}->ping() > 0;
 	$self->{db}->disconnect if defined $self->{db};
 	return $self->connect;
 }
 
-# set  current user using the API (used for Vhffs::Object::add_history)
+=pod
+
+=head1 set_current_user
+
+$vhffs->set_current_user( $user );
+
+Set current user using the API (used for C<Vhffs::Object::add_history>)
+
+=cut
 sub set_current_user {
 	my $self = shift;
 	my $user = shift;
@@ -137,11 +198,30 @@
 	return $user;
 }
 
+=pod
+
+=head1 get_current_user
+
+my $user = $vhffs->get_current_user;
+
+Get current user using the API (used for C<Vhffs::Object::add_history>)
+
+=cut
 sub get_current_user {
 	my $self = shift;
 	return $self->{current_user};
 }
 
+=pod
+
+=head1 clear_current_user
+
+$vhffs->clear_current_user;
+
+Clear current user using the API. You should use it if Vhffs main class
+is persistent and potentially used by more than one user.
+
+=cut
 sub clear_current_user {
 	my $self = shift;
 	delete $self->{current_user};
@@ -151,46 +231,5 @@
 
 __END__
 
-=head1 NAME
-
-Vhffs::Main - The main class of Vhffs API : connect to the database, ...
-
-=head1 SYNOPSIS
-
-	use Vhffs::Main;
-	my $vhffs = init Vhffs::Main;
-	my $conf = $vhffs->get_config;
-
-=head1 DESCRIPTION
-
-The Vhffs::Main object is VERY important on VHFFS platform. When you
-invoke init Vhffs::Main, it creates a Vhffs::Main object, so : 
-
-	- It creates connections to backend
-
-	- Read configuration and create a Vhffs::Conf object
-
-The utility of this object if to have a Db connection and the config
-in one object.
-
-=head1 METHODS
-
-init() : initialize the object
-
-get_config() : Return a Vhffs::Conf object
-
-get_db_object : Return a DBI object
-
-is_connected() : returns 1 if the backend connection is working, 0 otherwise
-
 =head1 SEE ALSO
 Vhffs::User, Vhffs::Group
-
-=head1 AUTHOR
-
-	Julien Delange <julien at gunnm dot org>
-
-=head1 COPYRIGHT
-
-	Copyright 2005 by Julien Delange
-