# Copyright 2008-2010 Tim Rayner
# 
# This file is part of Bio::MAGETAB.
# 
# Bio::MAGETAB 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.
# 
# Bio::MAGETAB 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 Bio::MAGETAB.  If not, see <http://www.gnu.org/licenses/>.
#
# $Id: Persistence.pm 361 2011-04-18 20:01:51Z tfrayner $

package Bio::MAGETAB::Util::Persistence;

use Moose;
use MooseX::FollowPBP;

use Carp;
use Tangram;
use DBI;

use MooseX::Types::Moose qw( Str HashRef ArrayRef );

# Uncomment these to print the SQL statements used to STDOUT.
#$Tangram::TRACE = \*STDOUT;
#$Tangram::DEBUG_LEVEL = 1;

sub class_config {

    my ( $class ) = @_;

    # This is where the magic happens. This needs to be kept synchronised
    # with any changes made to the core MAGETAB model.
    my $hashref = {

    classes => [

        'Bio::MAGETAB::ArrayDesign' => {
            bases  => [ 'Bio::MAGETAB::DatabaseEntry' ],
            fields => {
                string => { name             => {},
                            version          => {},
                            provider         => {},
                            printingProtocol => { sql => 'text default NULL' },
                            uri              => {}, },

                ref    => [ qw( technologyType
                                surfaceType
                                substrateType
                                sequencePolymerType )],

                array  => { designElements => 'Bio::MAGETAB::DesignElement', },
                iarray => { comments => { class  => 'Bio::MAGETAB::Comment',
                                          aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::Assay' => {
            bases  => [ 'Bio::MAGETAB::Event' ],
            fields => {
                ref => [ qw( arrayDesign
                             technologyType ) ],
            },
        },

        'Bio::MAGETAB::BaseClass' => {
            abstract => 1,
            fields   => {
                string => [ qw( authority namespace ) ],
            },
        },

        'Bio::MAGETAB::CompositeElement' => {
            bases  => [ 'Bio::MAGETAB::DesignElement' ],
            fields => {
                string => [ qw( name ) ],
                array  => { databaseEntries => 'Bio::MAGETAB::DatabaseEntry', },
                iarray => { comments => { class  => 'Bio::MAGETAB::Comment',
                                          aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::Comment' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( name
                                value ) ],
            },
        },

        'Bio::MAGETAB::Contact' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => { firstName    => {},
                            lastName     => {},
                            midInitials  => {},
                            email        => {},
                            organization => {},
                            phone        => {},
                            fax          => {},
                            address      => { sql => 'varchar(511) default NULL' }, },
                array  => { roles    => 'Bio::MAGETAB::ControlledTerm' },
                iarray => { comments => { class  => 'Bio::MAGETAB::Comment',
                                          aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::ControlledTerm' => {
            bases  => [ 'Bio::MAGETAB::DatabaseEntry' ],
            fields => {
                string => [ qw( category
                                value ) ],
            },
        },

        'Bio::MAGETAB::Data' => {
            abstract => 1,
            bases    => [ 'Bio::MAGETAB::Node' ],
            fields   => {
                string => [ qw( uri ) ],
                ref    => [ qw( dataType ) ],
            },
        },

        'Bio::MAGETAB::DataAcquisition' => {
            bases => [ 'Bio::MAGETAB::Event' ],
        },

        'Bio::MAGETAB::DatabaseEntry' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( accession ) ],
                ref    => [ qw( termSource ) ],
            },
        },

        'Bio::MAGETAB::DataFile' => {
            bases  => [ 'Bio::MAGETAB::Data' ],
            fields => {
                ref => [ qw( format ) ],
            },
        },
        
        'Bio::MAGETAB::DataMatrix' => {
            bases  => [ 'Bio::MAGETAB::Data' ],
            fields => {
                string => [ qw( rowIdentifierType ) ],
                iarray => { matrixColumns => { class  => 'Bio::MAGETAB::MatrixColumn',
                                               aggreg => 1 },
                            matrixRows    => { class  => 'Bio::MAGETAB::MatrixRow',
                                               aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::DesignElement' => {
            abstract => 1,
            bases    => [ 'Bio::MAGETAB::BaseClass' ],
            fields   => {
                string => [ qw( chromosome ) ],
                int    => [ qw( startPosition
                                endPosition ) ],
            },
        },

        'Bio::MAGETAB::Edge' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                ref   => [ qw( inputNode
                               outputNode ) ],
                array => { protocolApplications => 'Bio::MAGETAB::ProtocolApplication' },
            },
        },

        'Bio::MAGETAB::Event' => {
            abstract => 1,
            bases    => [ 'Bio::MAGETAB::Node' ],
            fields   => {
                string => [ qw( name ) ],
            },
        },

        'Bio::MAGETAB::Extract' => {
            bases => [ 'Bio::MAGETAB::Material' ],
            table => 'Bio_MAGETAB_Material',
        },

        'Bio::MAGETAB::Factor' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( name ) ],
                ref    => [ qw( factorType ) ],
            },
        },

        'Bio::MAGETAB::FactorValue' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {

                # N.B. measurement better as iref (which is not fully implemented yet).
                ref  => [ qw( term
                              measurement
                              factor ) ],
            },
        },

        'Bio::MAGETAB::Feature' => {
            bases  => [ 'Bio::MAGETAB::DesignElement' ],
            fields => {

                # N.B. column is a reserved word, we use col as an
                # abbreviation (and blockCol for consistency).
                int => [ qw( blockCol
                             blockRow
                             col
                             row ) ],
                ref => [ qw( reporter ) ],
            },
        },

        'Bio::MAGETAB::Investigation' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => { title             => {},
                            description       => { sql => 'text default NULL'},
                            date              => {},
                            publicReleaseDate => {}, },
                array  => { contacts            => 'Bio::MAGETAB::Contact',
                            protocols           => 'Bio::MAGETAB::Protocol',
                            publications        => 'Bio::MAGETAB::Publication',
                            termSources         => 'Bio::MAGETAB::TermSource',
                            designTypes         => 'Bio::MAGETAB::ControlledTerm',
                            normalizationTypes  => 'Bio::MAGETAB::ControlledTerm',
                            replicateTypes      => 'Bio::MAGETAB::ControlledTerm',
                            qualityControlTypes => 'Bio::MAGETAB::ControlledTerm', },
                iarray => { comments => { class  => 'Bio::MAGETAB::Comment',
                                          aggreg => 1 },
                            factors  => { class  => 'Bio::MAGETAB::Factor',
                                          aggreg => 1 },
                            sdrfs    => { class  => 'Bio::MAGETAB::SDRF',
                                          aggreg => 1 }, },
            },
        },
        
        'Bio::MAGETAB::LabeledExtract' => {
            bases   => [ 'Bio::MAGETAB::Material' ],
            fields  => {
                ref => [ qw( label ) ],
            },
        },

        'Bio::MAGETAB::Material' => {
            abstract => 1,
            bases    => [ 'Bio::MAGETAB::Node' ],
            fields   => {
                string => [ qw( name description ) ],
                ref    => [ qw( materialType ) ],
                array  => { characteristics => 'Bio::MAGETAB::ControlledTerm' },
                iarray => { measurements => { class  => 'Bio::MAGETAB::Measurement',
                                              aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::MatrixColumn' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                int   => [ qw( columnNumber ) ],
                ref   => [ qw( quantitationType ) ],
                array => { referencedNodes => 'Bio::MAGETAB::Node' },
            },
        },

        'Bio::MAGETAB::MatrixRow' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                int => [ qw( rowNumber ) ],
                ref => [ qw( designElement ) ],
            },
        },

        'Bio::MAGETAB::Measurement' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( measurementType
                                value
                                minValue
                                maxValue ) ],
                ref    => [ qw( unit ) ],
            },
        },

        'Bio::MAGETAB::Node' => {
            abstract => 1,
            bases    => [ 'Bio::MAGETAB::BaseClass' ],
            table    => 'Bio_MAGETAB_BaseClass',
            fields   => {
                array  => { sdrfRows    => 'Bio::MAGETAB::SDRFRow', },
                iarray => { inputEdges  => { class  => 'Bio::MAGETAB::Edge',
                                             aggreg => 1 },
                            outputEdges => { class  => 'Bio::MAGETAB::Edge',
                                             aggreg => 1 },
                            comments    => { class  => 'Bio::MAGETAB::Comment',
                                             aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::Normalization' => {
            bases => [ 'Bio::MAGETAB::Event' ],
            table => 'Bio_MAGETAB_Event',
        },

        'Bio::MAGETAB::ParameterValue' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {

                # N.B. measurement better as iref (which is not fully implemented yet).
                ref    => [ qw( parameter measurement term ) ],
                iarray => { comments => { class  => 'Bio::MAGETAB::Comment',
                                          aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::Protocol' => {
            bases  => [ 'Bio::MAGETAB::DatabaseEntry' ],
            fields => {
                string => { name     => {},
                            text     => { sql => 'text default NULL' },
                            software => {},
                            hardware => {},
                            contact  => {}, },
                ref    => [ qw( protocolType ) ],
            },
        },

        'Bio::MAGETAB::ProtocolApplication' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( date ) ],
                ref    => [ qw( protocol ) ],
                array  => { performers => 'Bio::MAGETAB::Contact' },
                iarray => { comments        => { class  => 'Bio::MAGETAB::Comment',
                                                 aggreg => 1 },
                            parameterValues => { class  => 'Bio::MAGETAB::ParameterValue',
                                                 aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::ProtocolParameter' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( name ) ],
                ref    => [ qw( protocol ) ],
            },
        },

        'Bio::MAGETAB::Publication' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => { title      => { sql => 'varchar(511) default NULL' },
                            authorList => { sql => 'varchar(511) default NULL' },
                            pubMedID   => {},
                            DOI        => {}, },
                ref    => [ qw( status ) ],
            },
        },

        'Bio::MAGETAB::Reporter' => {
            bases  => [ 'Bio::MAGETAB::DesignElement' ],
            fields => {
                string => [ qw( name sequence ) ],
                ref    => [ qw( controlType ) ],
                array  => { compositeElements => 'Bio::MAGETAB::CompositeElement',
                            databaseEntries   => 'Bio::MAGETAB::DatabaseEntry',
                            groups            => 'Bio::MAGETAB::ControlledTerm', },
            },
        },

        'Bio::MAGETAB::SDRF' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( uri ) ],
                iarray => { sdrfRows => { class  => 'Bio::MAGETAB::SDRFRow',
                                          aggreg => 1 }, },
            },
        },

        'Bio::MAGETAB::SDRFRow' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                int   => [ qw( rowNumber ) ],
                array => { nodes        => 'Bio::MAGETAB::Node',
                           factorValues => 'Bio::MAGETAB::FactorValue', },
                ref   => [ qw( channel ) ],
            },
        },

        'Bio::MAGETAB::Sample' => {
            bases => [ 'Bio::MAGETAB::Material' ],
            table => 'Bio_MAGETAB_Material',
        },

        'Bio::MAGETAB::Source' => {
            bases  => [ 'Bio::MAGETAB::Material' ],
            table  => 'Bio_MAGETAB_Material',
            fields => {
                array  => { providers => 'Bio::MAGETAB::Contact' },
            },
        },

        'Bio::MAGETAB::TermSource' => {
            bases  => [ 'Bio::MAGETAB::BaseClass' ],
            fields => {
                string => [ qw( name
                                uri
                                version ) ],
            },
        },
    ],

    # Instantiation of persistent objects in the database needs to
    # circumvent the Moose type constraints during any
    # Tangram::Storage->select( $remote, $filter ) calls. This just
    # returns a blessed hashref; the final objects still obey the
    # original constraints, however.
    make_object => sub { my $class = shift; return bless {}, $class },

    };
}

has 'config'   => ( is       => 'rw',
                    isa      => HashRef,
                    required => 1,
                    default  => \&class_config, );

# We delegate quite a lot to the associated Tangram::Storage
# instance. We could delegate even more, although tests should then be
# written to ensure the delegated calls are functioning correctly.
has 'store'    => ( is       => 'rw',
                    isa      => 'Tangram::Storage',
                    handles  => [qw( insert
                                     select
                                     update
                                     erase
                                     id
                                     count
                                     sum
                                     cursor
                                     remote )] );

has 'dbparams' => ( is         => 'ro',
                    isa        => ArrayRef,
                    required   => 1,
                    auto_deref => 1, );

sub BUILD {

    my ( $self, $params ) = @_;

    unless ( defined $params->{ 'dbparams' }[0] ) {
        croak("Error: Database DSN must be specified.\n");
    }
}

sub deploy {

    my ( $self ) = @_;

    my $dbh = DBI->connect( $self->get_dbparams() );

    Tangram::Relational->deploy( $self->get_schema(), $dbh );

    $dbh->disconnect();

    return;
}

sub get_schema {

    my ( $self ) = @_;

    return Tangram::Relational->schema( $self->get_config() );
}

sub connect {

    my ( $self ) = @_;

    my $store = Tangram::Relational->connect( $self->get_schema(), $self->get_dbparams() );

    $self->set_store( $store );

    return;
}

# Make the classes immutable. In theory this speeds up object
# instantiation for a small compilation time cost.
__PACKAGE__->meta->make_immutable();

no Moose;

=head1 NAME

Bio::MAGETAB::Util::Persistence - A Tangram-based object persistence
class for MAGE-TAB.

=head1 SYNOPSIS

 use Bio::MAGETAB::Util::Persistence;
 my $db = Bio::MAGETAB::Util::Persistence->new({
    dbparams       => [ "dbi:mysql:$dbname", $user, $pass ],
 });

 $db->deploy();
 $db->connect();
 $db->insert( $magetab_object );

=head1 DESCRIPTION

This class provides an object persistence mechanism for storing
MAGE-TAB objects in a relational database. The class is, in effect,
just a thin wrapper around a Tangram::Storage instance which
implements most of the database interaction methods. The class has
been used successfully with both MySQL and SQLite database backends,
and should in theory be usable with any database engine supported by
the Tangram modules.

=head1 ATTRIBUTES

=over 2

=item dbparams

A reference to an array containing database connection
parameters. This array is passed directly to C<DBI-E<gt>connect()>.

=item config

The Tangram schema definition used to create the database. This
attribute is read-only.

=item store

The underlying Tangram::Storage object used for most of the
interaction with the database.

=back

=head1 METHODS

=over 2

=item deploy

Connect to the database and deploy the schema. This only needs to be
done once to set up the database.

=item connect

Connect to the database. This must be done before using any of the
following methods.

=item get_schema

Returns the Tangram::Schema object created using the config attribute.

=item class_config

A class method which returns the config hash reference used to create
the Tangram::Schema object.

=item insert

=item select

=item update

=item erase

=item id

=item count

=item sum

=item cursor

=item remote

All these methods are delegated directly to the Tangram::Storage
object created by the C<connect> method, and contained within the
Persistence object. Please see the Tangram documentation for more
information on these methods.

=back

=head1 SEE ALSO

L<Bio::MAGETAB::DBLoader>
L<http://tangram.utsl.gen.nz/>

=head1 AUTHOR

Tim F. Rayner <tfrayner@gmail.com>

=head1 LICENSE

This library is released under version 2 of the GNU General Public
License (GPL).

=cut

1;