source: LATMOS-Accounts/lib/LATMOS/Accounts/Bases.pm @ 103

package LATMOS::Accounts::Bases;

use 5.010000;
use strict;
use warnings;
use LATMOS::Accounts::Bases::Objects;

our $VERSION = (q$Rev$ =~ /^Rev: (\d+) /)[0];

=head1 NAME

LATMOS::Accounts::Bases - Base class for account data bases

=head1 SYNOPSIS

  use LATMOS::Accounts::Bases;
  my $base = LATMOS::Accounts::Bases->new('type', %options);
  ...

=head1 DESCRIPTION

This module provide basic functions for various account base

=head1 FUNTIONS

=cut

=head2 new($type, %options)

Return, if success, a new data base account object, $type is
account base type, %options to setup the base.

=cut

sub new {
    my ($class, $type, %options) = @_;

    my $pclass = ucfirst(lc($type));
    eval "require LATMOS::Accounts::Bases::$pclass;";
    if ($@) { return } # error message ?
    my $base = "LATMOS::Accounts::Bases::$pclass"->new(%options);
    $base->{_type} = lc($pclass);
    $base->{_label} = $options{label};
    $base
}

sub label {
    $_[0]->{_label};
}

sub type {
    $_[0]->{_type};
}

sub _load_obj_class {
    my ($self, $otype) = @_;

    # finding perl class:
    my $pclass = ref $self;
    $pclass .= '::' . ucfirst(lc($otype));
    eval "require $pclass;";
    if ($@) { return } # error message ?
    return $pclass;
}

=head2 list_canonical_fields($otype, $for)

Return the list of supported fields by the database for object type $otype.

Optionnal $for specify the goal for which the list is requested, only supported
fields will be returns

=cut

sub list_canonical_fields {
    my ($self, $otype, $for) = @_;
    $for ||= 'rw';
    my $pclass = $self->_load_obj_class($otype) or return;
    $pclass->_canonical_fields($self, $for);
}

sub delayed_fields {
    my ($self, $otype, $for) = @_;
    $for ||= 'rw';
    my $pclass = $self->_load_obj_class($otype) or return;
    $pclass->_delayed_fields($self, $for);
}

=head2 get_field_name($otype, $c_fields, $for)

Return the internal fields name for $otype object for
canonical fields $c_fields

=cut

sub get_field_name {
    my ($self, $otype, $c_fields, $for) = @_;
    $for ||= 'rw';
    my $pclass = $self->_load_obj_class($otype) or return;
    $pclass->_get_field_name($c_fields, $self, $for);
}

=head2 list_supported_objects(@otype)

Return a list of supported object

@type is an additionnal list of objects to check

=cut

sub list_supported_objects {
    my ($self, @otype) = @_;
    return grep { $self->is_supported_object($_) }
        (qw(group user), @otype);
}

=head2 is_supported_object($otype)

Return true is object type $otype is supported

=cut

sub is_supported_object {
    my ($self, $otype) = @_;
    return $self->_load_obj_class($otype) ? 1 : 0;
}

=head2 list_objects($otype)

Return the list of UID for object of $otype.

=cut

sub list_objects {
    my ($self, $otype) = @_;
    my $pclass = $self->_load_obj_class($otype) or return;
    $pclass->list($self);
}

=head2 get_object($type, $id)

Return an object of $type (typically user or group) having identifier
$id.

=cut

sub get_object {
    my ($self, $otype, $id) = @_;

    return LATMOS::Accounts::Bases::Objects->_new($self, $otype, $id);
}

=head2 create_object($type, $id, %data)

Create and return an object of type $type with unique id
$id having %data.

This method should be provided by the data base handler.

=cut

sub create_object {
    my ($self, $otype, $id, %data) = @_;
    my $pclass = $self->_load_obj_class($otype);
    $pclass->_create($self, $id, %data) or return;
    $self->get_object($otype, $id);
}

=head2 create_c_object($type, $id, %data)

Create and return an object of type $type with unique id
$id having %data using canonical fields

=cut

sub create_c_object {
    my ($self, $otype, $id, %cdata) = @_;

    my %data;
    foreach my $cfield (keys %cdata) {
        my $field = $self->get_field_name($otype, $cfield, 'write') or next;
        $data{$field} = $cdata{$cfield};
    }
    keys %data or return 0; # TODO: return an error ?
    $self->create_object($otype, $id, %data);
}

=head2 delete_object($otype, $id)

Destroy from data base object type $otype having id $id.

=cut

sub delete_object {
    my ($self, $otype, $id) = @_;
    my $pclass = $self->_load_obj_class($otype);
    $pclass->_delete($self, $id) or return;
}

=head2 load

Make account base loading data into memory if need.
Should always be called, if database fetch data on the fly
(SQL, LDAP), the function just return True.

=cut

sub load { 1 }

=head2 is_transactionnal

Return True is the database support commit and rollback

=cut

sub is_transactionnal {
    my ($self) = @_;
    return($self->can('_rollback') && $self->can('_commit'));
}

=head2 commit

Save change into the database if change are not done immediately.
This should always be called as you don't know when change are applied.

Return always true if database does not support any transaction.

The driver should provides a _commit functions to save data.

=cut

sub commit {
    my ($self) = @_;
    return $self->can('_commit') ? $self->_commit : 1;
}

=head2 rollback

If database support transaction, rollback changes. Return false
if database does not support.

If supported, driver should provides a _rollback functions

=cut

sub rollback {
    my ($self) = @_;
    return $self->can('_rollback') ? $self->_rollback : 0;
}

=head2 current_rev

Return the current revision of the database

Must be provide by base driver if incremental synchro is supported

=cut

sub current_rev { return }

=head2 list_objects_from_rev($otype, $rev)

Return the list of UID for object of $otype.

=cut

sub list_objects_from_rev {
    my ($self, $otype, $rev) = @_;
    my $pclass = $self->_load_obj_class($otype) or return;
    if (defined($rev) && $pclass->can('list_from_rev')) {
        return $pclass->list_from_rev($self, $rev);
    } else {
        # no support, return all objects...
        return $self->list_objects($otype);
    }
}

=head2 sync_object

Synchronise an object into this base

=cut

sub sync_object {
    my ($self, $srcobj, %options) = @_;
    $self->is_supported_object($srcobj->type) or return;
    my @fields = $options{attrs}
        ? @{ $options{attrs} }
        : $self->list_canonical_fields($srcobj->type, 'w');
    my %data;
    foreach (@fields) {
        $srcobj->get_field_name($_, 'r') or next;
        $data{$_} = $srcobj->get_c_field($_);
    }
    if (my $dstobj = $self->get_object($srcobj->type, $srcobj->id)) {
        return $dstobj->set_c_fields(%data);
    } elsif(!$options{nocreate}) {
        return $self->create_c_object($srcobj->type, $srcobj->id, %data);
    } else {
        return 0;
    }
}

1;

__END__

=head1 SEE ALSO

=head1 AUTHOR

Thauvin Olivier, E<lt>olivier.thauvin@latmos.ipsl.fr<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2009 by Thauvin Olivier

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.0 or,
at your option, any later version of Perl 5 you may have available.

=cut