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

Annotation of /Sprout/DBQuery.pm

Parent Directory Parent Directory | Revision Log Revision Log


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

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

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3