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

Annotation of /Sprout/DBQuery.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (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 : parrello 1.6 $retVal = DBObject::_new($self, @row);
74 : parrello 1.4 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 : parrello 1.5 =item relationMap
99 : parrello 1.1
100 : parrello 1.5 Reference to a list of 2-tuples. Each tuple consists of an object name as used in the
101 :     query followed by the actual name of that object. This enables the B<DBObject> to
102 :     determine the order of the tables in the query and which object name belongs to each
103 :     mapped object name. Most of the time these two values are the same; however, if a
104 :     relation occurs twice in the query, the relation name in the field list and WHERE
105 :     clause will use a mapped name (generally the actual relation name with a numeric
106 :     suffix) that does not match the actual relation name.
107 : parrello 1.1
108 : parrello 1.6 =item searchObject (optional)
109 :    
110 :     If specified, then the query is a full-text search, and the first field will be a
111 :     relevance indicator for the named table.
112 :    
113 : parrello 1.1 =back
114 :    
115 :     =cut
116 :    
117 :     sub _new {
118 : parrello 1.4 # Get the parameters.
119 : parrello 1.6 my ($database, $sth, $relationMap, $searchObject) = @_;
120 : parrello 1.4 # Create this object.
121 : parrello 1.6 my $self = { _db => $database, _sth => $sth, _objectNames => $relationMap,
122 :     _fullText => $searchObject };
123 : parrello 1.4 # Bless and return it.
124 :     bless $self;
125 :     return $self;
126 : parrello 1.1 }
127 :    
128 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3