# $Id: GraphAdaptor.pm 10525 2006-09-26 22:03:22Z sendu $
#
# BioPerl Graph adaptor for Bio::Ontology::SimpleGOEngine
#
# Please direct questions and support issues to <bioperl-l@bioperl.org> 
#
# Cared for by Nat Goodman <natg at shore.net>
#
# (c) Nathan Goodman natg@shore.net 2005
# (c) ISB, Institute for Systems Biology 2005
#
# You may distribute this module under the same terms as perl itself.
# Refer to the Perl Artistic License (see the license accompanying this
# software package, or see http://www.perl.com/language/misc/Artistic.html)
# for the terms under which you may use, modify, and redistribute this module.
#
# THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
# WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
# MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#
# You may distribute this module under the same terms as perl itself

# POD documentation - main docs before the code

=head1 NAME

Bio::Ontology::SimpleGOEngine::GraphAdaptor - Graph adaptor for
Bio::Ontology::SimpleGOEngine

=head1 SYNOPSIS

  use Bio::Ontology::SimpleGOEngine::GraphAdaptor;

  my $graph = Bio::Ontology::SimpleGOEngine::GraphAdaptor;

=head1 DESCRIPTION

This is a think adaptor to simplify use of the old and new versions of
the standard CPAN Graph module (old is versions 0.2x; new is 0.5x and
beyond) within Bio::Ontology::SimpleGOEngine.

This module implements only those Graph methods used by
SimpleGOEngine.  It is far from a complete compatibility layer!  It
also implements workarounds for cerain performance problems in the
current versions of Graph v0.5x.

This class provides a 'new' method that determines which version of
Graph is available.  The object returned by 'new' is blessed into this
class if the new version of Graph is available, else into the subclass

  Bio::Ontology::SimpleGOEngine::GraphAdaptor02

This class provides implementations for the required graph methods
using the new version of Graph.  In most cases, these are simple
pass-throughs.  Methods that differ in v0.2x are implemented in the
subclass.

The methods implemented here or in the subclasses are listed below.
In all cases, we implemented the Graph v0.5x interface.  Consult the
Graph v0.5x man page for details.

  add_vertex
  has_vertex
  add_edge
  has_edge
  vertices
  edges
  edges_at
  predecessors
  successors
  set_vertex_attribute
  get_vertex_attribute
  set_edge_attribute
  get_edge_attribute
  source_vertices
  sink_vertices

=head1 FEEDBACK

=head2 Mailing Lists

User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to the
Bioperl mailing lists  Your participation is much appreciated.

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

=head2 Support 

Please direct usage questions or support issues to the mailing list:

I<bioperl-l@bioperl.org>

rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.

=head2 Reporting Bugs

report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution.  Bug reports can be submitted via the
web:

  http://bugzilla.open-bio.org/

=head1 AUTHOR

Nat Goodman

Email: natg at shore.net

Address:

  Institute for Systems Biology
  1441 N 34th St
  Seattle, WA 98103-8904

=head1 APPENDIX

The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _

=cut

# Let the code begin...

package Bio::Ontology::SimpleGOEngine::GraphAdaptor;

use Graph::Directed;

use strict;
use Bio::Ontology::SimpleGOEngine::GraphAdaptor02;

use base qw(Bio::Root::Root);

=head2 new

 Title   : new
 Usage   : $graph = Bio::Ontology::SimpleGOEngine::GraphAdaptor->new()
 Function: Creates a new graph
 Returns : Bio::Ontology::SimpleGOEngine::GraphAdaptor02 or 
           Bio::Ontology::SimpleGOEngine::GraphAdaptor05 object, 
           depending on which Graph version is available
 Args    : none

=cut

sub new {
  my( $class ) = @_;
  $class = ref $class || $class;

  my $self=
    ( defined $Graph::VERSION && $Graph::VERSION >= 0.5 ) ?
      bless ( {}, $class ) :
	bless ( {}, 'Bio::Ontology::SimpleGOEngine::GraphAdaptor02' );
  $self->{_graph}=new Graph::Directed;
  $self->{_vertex_attributes}={};
  $self->{_edge_attributes}={};
  return $self;
}

# Here are the main methods

sub add_vertex {
  my $self=shift;
  $self->_graph->add_vertex(@_);
}
sub has_vertex {
  my $self=shift;
  $self->_graph->has_vertex(@_);
}
sub add_edge {
  my $self=shift;
  $self->_graph->add_edge(@_);
}
sub has_edge {
  my $self=shift;
  $self->_graph->has_edge(@_);
}
sub vertices {
  my $self=shift;
  $self->_graph->vertices(@_);
}
sub edges {
  my $self=shift;
  $self->_graph->edges(@_);
}
sub edges_at {
  my $self=shift;
  $self->_graph->edges_at(@_);
}
sub predecessors {
  my $self=shift;
  $self->_graph->predecessors(@_);
} 
sub successors {
  my $self=shift;
  $self->_graph->successors(@_);
}
sub source_vertices {
  my $self=shift;
  $self->_graph->source_vertices();
}
sub sink_vertices {
  my $self=shift;
  $self->_graph->sink_vertices();
}
# The following methods workaround a performance problem in Graph v0.5x 
# when attributes are attached to the graph
sub set_vertex_attribute {
  my($self,$v,$attribute,$value)=@_;
  $self->_vertex2attributes($v)->{$attribute}=$value;
}
sub get_vertex_attribute {
  my($self,$v,$attribute)=@_;
  $self->_vertex2attributes($v)->{$attribute};
}
sub set_edge_attribute {
  my($self,$u,$v,$attribute,$value)=@_;
  $self->_edge2attributes($u,$v)->{$attribute}=$value;
}
sub get_edge_attribute {
  my($self,$u,$v,$attribute)=@_;
  $self->_edge2attributes($u,$v)->{$attribute};
}

=head2 _graph

 Title   : _graph
 Usage   : $self->_graph();
 Function: Internal method to access 'real' graph
 Returns : Graph::Directed object 
 Args    : none

=cut

sub _graph {$_[0]->{_graph}; }

=head2 _vertex_attributes

 Title   : _vertex_attributes
 Usage   : $self->vertex_attributes();
 Function: Internal method to access HASH used to store vertex attributes
 Returns : Graph::Directed object 
 Args    : none

=cut

sub _vertex_attributes {$_[0]->{_vertex_attributes}; }

=head2 _edge_attributes

 Title   : _edge_attributes
 Usage   : $self->edge_attributes();
 Function: Internal method to access HASH used to store edge attributes
 Returns : Graph::Directed object 
 Args    : none

=cut

sub _edge_attributes {$_[0]->{_edge_attributes}; }

=head2 _vertex2attributes

 Title   : _vertex2attributes
 Usage   : $value=$graph->_vertex2attributes($v_->{ATTRIBUTE};
           $graph->_vertex2attributes($v)->{ATTRIBUTE}=$value;
 Function: Internal method to access attributes for a specific vertex
 Returns : HASH
 Args    : none

=cut

sub _vertex2attributes {
  my($self,$vertex)=@_;
  $self->_vertex_attributes->{$vertex} or $self->_vertex_attributes->{$vertex}={};
}

=head2 _edge2attributes

 Title   : _edge2attributes
 Usage   : $value=$graph->_edge2attributes($u,$v)->{ATTRIBUTE};
           $graph->_edge2attributes($u,$v)->{ATTRIBUTE}=$value;
 Function: Internal method to access HASH used to store edge attributes
 Returns : HASH
 Args    : none

=cut

sub _edge2attributes {
  my($self,$u,$v)=@_;
  $self->_edge_attributes->{$u,$v} or $self->_edge_attributes->{$u,$v}={};
}

1;