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

Annotation of /Sprout/DBQuery.pm

Parent Directory Parent Directory | Revision Log Revision Log


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

1 : parrello 1.1 package DBQuery;
2 :    
3 : parrello 1.4 use strict;
4 :     use DBKernel;
5 : parrello 1.7 use ERDBObject;
6 : parrello 1.4 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 : parrello 1.8 entity iterator returns a single object at each position; the relationship iterator returns two
21 : parrello 1.1 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 : parrello 1.8 For example, a client could ask for all B<Feature> instances that are marked active. This would
25 : parrello 1.1 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 : parrello 1.7 At each point in the result set, the iterator returns a B<ERDBObject>. The ERDBObject allows the
32 : parrello 1.1 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 : parrello 1.8 sequences of entities together by relationships. This is discussed in the documentation for the
36 : parrello 1.1 B<ERDB> object's C<Get> method.
37 :    
38 :     Finally, objects of this type should never by created directly. Instead, they are created
39 : parrello 1.7 by the aforementioned C<Get> method and the B<ERDBObject>'s C<Cross> method.
40 : parrello 1.1
41 :     =head2 Public Methods
42 :    
43 :     =head3 Fetch
44 :    
45 : parrello 1.8 my $dbObject = $dbQuery->Fetch();
46 : parrello 1.1
47 : parrello 1.7 Retrieve a record from this query. The record returned will be a B<ERDBObject>, which
48 : parrello 1.1 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 : parrello 1.8 result set.
52 : parrello 1.1
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 :     # Here we have no result. If we're at the end of the result set, this is okay, because
66 :     # we'll be returning an undefined value in $retVal. If an error occurred, we need to abort.
67 :     if ($sth->err) {
68 : parrello 1.9 Confess("FETCH error: " . $sth->err);
69 :     } else {
70 :     # Trace the number of results returned.
71 :     Trace("$self->{_results} rows processed by query.") if T(SQL => 4);
72 : parrello 1.4 }
73 :     } else {
74 :     # Here we have a result, so we need to turn it into an instance object.
75 : parrello 1.7 $retVal = ERDBObject::_new($self, @row);
76 : parrello 1.9 $self->{_results}++;
77 : parrello 1.4 }
78 :     # Return the result.
79 :     return $retVal;
80 : parrello 1.1 }
81 :    
82 :     =head2 Utility Methods
83 :    
84 :     =head3 new (internal)
85 :    
86 :     Create a new query object.
87 :    
88 :     This is a static method.
89 :    
90 :     =over 4
91 :    
92 :     =item database
93 :    
94 :     ERDB object for the relevant database.
95 :    
96 :     =item sth
97 :    
98 :     Statement handle for the SELECT clause generated by the query.
99 :    
100 : parrello 1.5 =item relationMap
101 : parrello 1.1
102 : parrello 1.5 Reference to a list of 2-tuples. Each tuple consists of an object name as used in the
103 : parrello 1.7 query followed by the actual name of that object. This enables the B<ERDBObject> to
104 : parrello 1.5 determine the order of the tables in the query and which object name belongs to each
105 :     mapped object name. Most of the time these two values are the same; however, if a
106 :     relation occurs twice in the query, the relation name in the field list and WHERE
107 :     clause will use a mapped name (generally the actual relation name with a numeric
108 :     suffix) that does not match the actual relation name.
109 : parrello 1.1
110 : parrello 1.6 =item searchObject (optional)
111 :    
112 :     If specified, then the query is a full-text search, and the first field will be a
113 :     relevance indicator for the named table.
114 :    
115 : parrello 1.1 =back
116 :    
117 :     =cut
118 :    
119 :     sub _new {
120 : parrello 1.4 # Get the parameters.
121 : parrello 1.6 my ($database, $sth, $relationMap, $searchObject) = @_;
122 : parrello 1.4 # Create this object.
123 : parrello 1.6 my $self = { _db => $database, _sth => $sth, _objectNames => $relationMap,
124 : parrello 1.9 _fullText => $searchObject, _results => 0 };
125 : parrello 1.4 # Bless and return it.
126 :     bless $self;
127 :     return $self;
128 : parrello 1.1 }
129 :    
130 : parrello 1.8 1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3