NAME¶
Data::ObjectDriver::ResultSet - Manage a DB query
SYNOPSIS¶
# Get a resultset object for Object::Widget, which inherits from
# Data::ObjectDriver::BaseObject
my $result = Object::Widget->result($terms, $args);
$result->add_term({color => 'blue'});
$result->add_limit(10);
$result->add_offset(100);
while (not $result->is_empty) {
my $widget = $result->next;
# Do stuff with $widget
}
DESCRIPTION¶
This object is returned by the 'result' method found in the
Data::ObjectDriver::BaseObject class. This object manages a query and the
resulting data. It allows additional search terms and arguments to be added
and will not submit the query until a method that returns data is called. By
passing this object around code in multiple places can alter the query easily
until the data is needed.
Once a method returning data is called (next, count, etc) the query is submitted
to the database and the returned data is managed by the ResultSet object like
an iterator.
METHODS¶
$result_set = $class->result($terms, $args)¶
This method is actually defined in Data::ObjectDriver::BaseObject but it is the
way a new ResultSet object is created.
Arguments:
- $terms - A hashref. Same format as the
first argument to Data::ObjectDriver::DBI::search
- $args - A hashref. Same format as the
second argument to Data::ObjectDriver::DBI::search
Return value:
This method returns a Data::ObjectDriver::ResultSet object
$new_result =
Data::ObjectDriver::ResultSet->iterator(\@data)¶
Create a new result set object that takes existing data and operates only as an
iterator, without any of the query managment.
Arguments:
- $data - An array ref of data elements
Return value:
A Data::ObjectDriver::ResultSet object
add_constraint¶
Apply a constraint to the result. The format of the two arguments is the same as
for Data::ObjectDriver::DBI::search
Arguments:
- $terms - A hashref of object fields and values constraining
them. Same as first parameter to result method.
- $args - A hashref of values that affect the returned data,
such as limit and sort by. Same as first parameter to result
method.
; Return value : Returns
1 if successful and
0 otherwise
; Notes : Do we fail if called after we've retrieved the result set? Ignore it?
Requery?
; Example
$res->add_constraint({object_id => $id}, {limit => 100})
add_term¶
Apply a single search term to the result. Equivalent to:
$res->add_constraint($terms)
Arguments:
- $terms - A hashref of object fields and values constraining
them
; Return value : Returns
1 if successful and
0 otherwise
; Notes : Same question as for
add_constraint
; Example
$res->add_term({object_id => $id})
clear_term¶
Clear a single search term from the result.
Arguments:
- @terms - An array of term names to clear
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
none
; Example
$res->clear_term(qw(limit offset))
add_limit¶
Apply a limit to the result. Equivalent to:
$res->add_constraint({}, {limit => $limit})
Arguments:
- $limit - A scalar numeric value giving the limit of the
number of objects returned
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
; Example
$res->add_limit(100)
clear_limit¶
Clear any limit value in the result.
Arguments:
- none
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
None
; Example
$res->clear_limit
add_offset¶
Add an offset for the results returned. Result set must also have a limit set at
some point.
Arguments:
- $offset - A scalar numeric value giving the offset for the
first object returned
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
none
; Example
$res->add_offset(5_000)
clear_offset¶
Clear any offset value in the result.
Arguments:
- none
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
; Example
$res->clear_offset
add_order¶
Add a sort order for the results returned.
Arguments:
- [0] = $order = - A scalar string value giving the sort
order for the results, one of ascend or
descend
; Return value : Returns
1 if successful and
0 otherwise
; Notes : >none''
; Example
$res->add_order('ascend')
clear_order¶
Clear any offset value in the result.
Arguments:
- none
; Return value : Returns
1 if successful and
0 otherwise
; Notes :
none
; Example
$res->clear_order
index¶
Return the current index into the result set.
Arguments:
- none
; Return value : An integer giving the zero based index of the current element
in the result set.
; Notes :
none
; Example
$idx = $res->index;
next¶
Retrieve the next item in the resultset
Arguments:
- none
; Return value : The next object or undef if past the end of the result set
; Notes : Calling this method will force a DB query. All subsequent calls to
curr will return this object
; Example
$obj = $res->next;
peek_next¶
Retrieve the next item in the resultset WITHOUT advancing the cursor.
Arguments:
- none
; Return value : The next object or undef if past the end of the result set
; Notes : Calling this method will force a DB query. All subsequent calls to
curr will return this object
; Example
while ($bottle = $res->next){
if ($bottle->type eq 'Bud Light'
&& $res->peek_next->type eq 'Chimay'){
$bottle->pass; #don't spoil my palate
}else{
$bottle->drink;
}
}
prev¶
Retrieve the previous item in the result set
Arguments:
- none
; Return value : The previous object or undef if before the beginning of the
result set
; Notes : All subsequent calls to
curr will return this object
; Example
$obj = $res->prev;
curr¶
Retrieve the current item in the result set. This item is set by calls to
next and
prev
Arguments:
- none
; Return value : The current object or undef if past the boundaries of the
result set
; Notes :
none
; Example
$obj = $res->curr
slice¶
Return a slice of the result set. This is logically equivalent to setting a
limit and offset and then retrieving all the objects via
-next>. If
you call
slice and then call
next, you will get
undef and
additionally
is_empty will be true.
Arguments:
- $from - Scalar integer giving the start of the slice
range
- $to - Scalar integer giving the end of the slice range
; Return value : An array of objects
; Notes : Objects are index from 0 just like perl arrays.
; Example
my @objs = $res->slice(0, 20)
count¶
Get the count of the items in the result set.
Arguments:
- none
; Return value : A scalar count of the number of items in the result set
; Notes : This will cause a
count() query on the database if the result
set hasn't been retrieved yet. If the result set has been retrieved it will
just return the number of objects stored in the result set object.
; Example
$num = $res->count
is_finished¶
Returns whether we've arrived at the end of the result set
Arguments:
- none
; Return value : Returns
1 if we are finished iterating though the result
set and
0 otherwise
; Notes :
none
; Example
while (not $res->is_finished) {
my $obj = $res->next;
# Stuff ...
}
dod_debug¶
Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to get the
results.
rewind¶
Move back to the start of the iterator for this instance of results of a query.
first¶
Returns the first object in the result set.
Arguments:
- none
; Return value : The first object in the result set
; Notes : Resets the current cursor so that calls to
curr return this
value.
; Example
$obj = $res->first
last¶
Returns the last object in the result set.
Arguments:
- none
; Return value : The last object in the result set
; Notes : Resets the current cursor so that calls to
curr return this
value.
; Example
$obj = $res->last
is_last¶
Returns 1 if the cursor is on the last row of the result set, 0 if it is not.
Arguments:
- none
; Return value : Returns
1 if the cursor is on the last row of the result
set,
0 if it is not.
; Example
if ( $res->is_last ) {
## do some stuff
}