[Bio] / Sprout / DBQuery.pm Repository:
ViewVC logotype

Annotation of /Sprout/DBQuery.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (view) (download) (as text)

1 : parrello 1.1 package DBQuery;
2 :    
3 :     use strict;
4 :     use DBKernel;
5 :     use DBObject;
6 :     use DBI;
7 :     use Carp;
8 :     use Tracer;
9 :    
10 :     =head1 Entity-Relationship Database Package Query Iterator
11 :    
12 :     =head2 Introduction
13 :    
14 :     This package defines the Iteration object for an Entity-Relationship Database. The iteration object
15 :     represents a filtered SELECT statement against an Entity-Relationship Database, and provides
16 :     methods for getting the appropriate records.
17 :    
18 :     There are two common ways an iteration object can be created. An I<entity iterator> is created when the
19 :     client asks for objects of a given entity type. A I<relationship iterator> is created when the
20 :     client asks for objects across a relationship starting from a specific entity instance. The
21 :     entity iterator returns a single object at each position; the relationship iterator returns two
22 :     objects at each position-- one for the target entity, and one for the relationship instance
23 :     that connects it to the source entity.
24 :    
25 :     For example, a client could ask for all B<Feature> instances that are marked active. This would
26 :     return an entity iterator. Each position in the iteration would consist of a single
27 :     B<Feature> instance. From a specific B<Feature> instance, the client could decide to cross the
28 :     B<IsLocatedIn> relationship to get all the B<Contig> instances which contain residues that
29 :     participate in the feature. This would return a relationship iterator. Each position in the
30 :     iterator would contain a single B<IsLocatedIn> instance and a single B<Contig> instance.
31 :    
32 :     At each point in the result set, the iterator returns a B<DBObject>. The DBObject allows the
33 :     client to access the fields of the current entity or relationship instance.
34 :    
35 :     It is also possible to ask for many different objects in a single iterator by chaining long
36 :     sequences of entities together by relationships. This is discussed in the documentation for the
37 :     B<ERDB> object's C<Get> method.
38 :    
39 :     Finally, objects of this type should never by created directly. Instead, they are created
40 :     by the aforementioned C<Get> method and the B<DBObject>'s C<Cross> method.
41 :    
42 :     =head2 Public Methods
43 :    
44 :     =head3 Fetch
45 :    
46 :     C<< my $dbObject = $dbQuery->Fetch(); >>
47 :    
48 :     Retrieve a record from this query. The record returned will be a B<DBObject>, which
49 :     may represent a single entity instance or a list of entity instances joined by relationships.
50 :     The first time this method is called it will return the first result from query. After that it
51 :     will continue sequentially. It will return an undefined value if we've reached the end of the
52 :     result set.
53 :    
54 :     =cut
55 :    
56 :     sub Fetch {
57 :     # Get the parameters;
58 : parrello 1.2 my ($self) = @_;
59 : parrello 1.1 # Declare the return variable.
60 :     my $retVal;
61 :     # Fetch the next row in the query result set.
62 :     my $sth = $self->{_sth};
63 :     my @row = $sth->fetchrow;
64 :     # Check to see if we got any results.
65 :     if (@row == 0) {
66 :     Trace("No result from query.") if T(3);
67 :     # Here we have no result. If we're at the end of the result set, this is okay, because
68 :     # we'll be returning an undefined value in $retVal. If an error occurred, we need to abort.
69 :     if ($sth->err != 0) {
70 :     Confess("FETCH error");
71 :     }
72 :     } else {
73 :     # Here we have a result, so we need to turn it into an instance object.
74 :     $retVal = DBObject::_new($self->{_db}, $self->{_objectNames}, @row);
75 :     Trace("Row returned from query.") if T(4);
76 :     }
77 :     # Return the result.
78 :     return $retVal;
79 :     }
80 :    
81 :     =head2 Utility Methods
82 :    
83 :     =head3 new (internal)
84 :    
85 :     Create a new query object.
86 :    
87 :     This is a static method.
88 :    
89 :     =over 4
90 :    
91 :     =item database
92 :    
93 :     ERDB object for the relevant database.
94 :    
95 :     =item sth
96 :    
97 :     Statement handle for the SELECT clause generated by the query.
98 :    
99 :     =item objectName1, objectName2, ...
100 :    
101 :     Names of the objects being retrieved.
102 :    
103 :     =back
104 :    
105 :     =cut
106 :    
107 :     sub _new {
108 :     # Get the parameters.
109 :     my ($database, $sth, @objectNames) = @_;
110 :     # Create this object.
111 :     my $self = { _db => $database, _sth => $sth, _objectNames => \@objectNames };
112 :     # Bless and return it.
113 :     bless $self;
114 :     return $self;
115 :     }
116 :    
117 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3