NAME
Persist::Driver - Base class for Persist drivers
SYNOPSIS
package Some::Driver;
use Persist qw(:constants);
use Persist::Driver;
@ISA = qw( Persist::Driver );
sub new { ... }
sub is_dba { ... }
sub new_source { ... }
sub delete_source { ... }
sub new_table { ... }
sub delete_table { ... }
sub tables { ... }
sub open_table { ... }
sub open_join { ... }
sub insert { ... }
sub update { ... }
sub delete { ... }
sub columns { ... }
sub indexes { ... }
sub first { ... }
sub next { ... }
sub sequence_value { ... }
DESCRIPTION
This module defines the functionality required for all Persist drivers. The interface is meant to be independent of the backing store architecture. It should be able to relatively easily provide access to SQL database, LDAP directories, memory structures, file structures, etc.
Implementors should never call the SUPER
version of any method in this package as they are all defined to die with an error message.
CHANGES FOR 0.5.0
As of the 0.5.0 release of Persist, the way drivers are written has changed. This change has been made for reasons of flexibility. Instead of taking positional paramters, all driver arguments will be passed in hyphen-named format. This will allow features to be added more easiler in the future.
NOTATION
Before getting into the method descriptions, a discussion on notation is required. Arguments are passed to driver methods using a hyphen-named parameter passing format--one that is used in a number of important Perl packages.
Basically, each method that takes arguments, accepts them in a single hash, which is always called %args
in this documentation. Then a list of arguments is shown in the description of the method. The descriptions will give a general indication of the base-type required and the name of the argument, along with noting whether the argument is optional or not (a parameter is required unless otherwise noted).
For example, if there were a method "foo" described with these parameters:
Then, the method "foo" requires a scalar value passed as "-foo" and may have a parameter "-bar" that takes array reference. Thus, this could be a legal call for this fictional method:
$driver->foo(-foo => "baz", -bar => [ 1, 2, 3 ]);
Make sure to read the details of the parameter as it may provide further stipulations on the type.
METHODS
- $driver = new Persist::Driver(%args)
-
The implementation may define any arguments it likes to be passed to the constructor. What the constructor does is completely up to the implementation.
- $test = $driver->is_dba
-
Returns whether the connection is for a DBA/sysadmin user. This basically tells us whether or not a call to
new_source
anddelete_source
can succeed. - @connect_args = $driver->new_source(%args)
-
Creates a new data source if the current user is capable. It returns the arguments required to connect to this new database. The arguments that must be passed to the driver to create a connection are driver dependent.
- $success = $driver->delete_source(%args)
-
Deletes an existing data source if the current user is capable. It returns true upon success. The arguments that must be passed to delete the source are driver dependent.
- $success = $driver->create_table(%args)
-
Creates a new ``table'' in the data source. Even if the data source is not relational, the closest approximation to a table should be used. The implementation should provide the columns presented in this definition with lenient typing--that is, a column should be able to hold all values of the type given, but isn't required to restrict the values to only that type. The indexes are provided as a general guideline, but are not required to be enforced. In general, though, enforcing at least the
PRIMARY
index is recommended.Even though a driver is not required to enforce them. It must, however, remember the settings for the purposes of the
indexes
method and for providing functionality for joining tables.The arguments
$args
accepted are:- $table
-
The name of the table to create.
- @columns
-
The column definition specification. This will be a series of keyword/value pairs. Each key is the name of the column and each value is the datatype descriptor. See Persist::Source for details. This will always be passed as an array reference, even though the front-end allows for this argument to be a hash reference.
- @indexes
-
Specifies a list of indexes to add to this table. See Persist::Source for details.
The method returns true on successful table creation.
- $success = $driver->delete_table(%args)
-
This operation will annihilate the table description and all data associated with it.
This method takes these arguments in
%args
:Returns true upon successful deletion of the table (or equivalent object in the store).
- @tables = $driver->tables
-
Returns a list of all the table names in the data source. This may return tables that were not created by the source (such as preexisting data), but should not return system tables or the equivalent.
- $handle = $driver->open_table(%args)
-
Returns a handle which may be used to fetch information out of a single table in the database.
The possible arguments
%args
are:- $table
-
The name of the table.
- $filter (optional)
-
The
$filter
argument may be used to narrow the results. See "FILTERS" in Persist::Filter for details on the format of$filter
. - @order (optional)
-
The
$order
argument may be used to determine the order in which records should be returned. The names of the order columns should match those selected (using SQL terms). Each column may be followed by the constantASC
(orASCENDING
) to assert ascending order (which is the default) or byDESC
(orDESCENDING
) to assert descending order. The constant applies to the immediately preceding column name only. - $offset (optional)
-
This is the 0-based index of the first record to return. If this index is beyond the last record in the database, the handle should return no records.
- $limit (optional)
-
This is the maximum number of calls to
next
that should return rows. The($limit + 1)
th call should returnundef
.
- $handle = $driver->open_join(%args)
-
Creates a handle to refer to for iterating over a selection of data in a set of tables. This join will be performed implicitly if no "-on" option is present. Otherwise, it will rely on the user to explicitly specify how the tables are to be joined.
Implicit joining occurs based upon the links between tables. If we think of links as a directed graph, the implicit join will use as many of the links between the tables as possible, without causing a loop in the graph. Which links are dropped when a set of tables contains a circular set of links is up to the driver itself. This specification recommends to driver writers that tables that occur later in the
@tables
list should be preferred when dropping links. This specification recommends to Persist users that they use an explicit join if there are circular links in a set of joined tables to make sure you get the join you are looking for.- @tables
-
The array
@tables
is a list of table names to join. - $filter (optional)
-
This specifies the filter to use to choose which rows to return. Only rows where the filter and join conditions are true will be returned.
See Persist::Filter for details on the format of the filters.
- @on (optional)
-
This specifies the filter to use to join the tables together. If specified, the
@on
array should be one element smaller than the@tables
array. The first element of the@on
array will be used to join the first and second tables in the@tables
array. The second element of the@on
array will be used to join the third table to the first and second tables in the@tables
array. This proceeds onward until the last@on
element will be used to join the last@tables
element to all the previous tables.See Persist::Filter for details on the format of the filters.
- @order (optional)
-
The
$order
argument may be used to determine the order in which records should be returned. The names of the order columns should match those selected (using SQL terms). Each column may be followed by the constantASC
(orASCENDING
) to assert ascending order (which is the default) or byDESC
(orDESCENDING
) to assert descending order. The constant applies to the immediately preceding column name only. - $offset (optional)
-
This is the 0-based index of the first record to return. If this index is beyond the last record in the database, the handle should return no records.
- $limit (optional)
-
This is the maximum number of calls to
next
that should return rows. The($limit + 1)
th call should returnundef
.
Returns a handle which may be used to fetch information out of a group of tables that are joined according to their
LINK
indexes. - $rows = $driver->insert(%args)
-
Inserts a new row into a table.
The arguments
%args
accepted are:- $table
-
The name of the table to insert into.
- %values
-
The hash
%values
maps column names (keys) to values (values).
The result is the number of rows modified (should always be one on success).
- $rows = $driver->update(%args)
-
Updates zero or more entries in a table.
The arguments
%args
accepted are:- $table
-
The name of the table to update.
- %set
-
The hash
%set
maps column names (keys) to values (values). - $filter (optional)
-
The optional filter specifies the criteria by which rows will be matched to determine whether or not to update them.
WARNING: An undefined filter will update all rows.
See "FILTERS" in Persist::Filter for details on the format of the filter.
- @bindings
-
The final optional bindings array is an array of bindings values.
Returns the number of rows affected.
- $rows = $driver->delete(%args)
-
Deletes zero or more entries from a table.
The arguments
%arg
accepted are:- $table
-
The name of the table to delete records from.
- $filter (optional)
-
The optional filter specifies the criteria by which rows will be matched for deletion.
WARNING: An undefined filter will delete all rows from the table.
See "FILTERS" in Persist::Filter for details on the format of the filter.
- @bindings (optional)
-
The final optional bindings argument is an array of binding values.
Returns the number of rows affected.
- %columns = $driver->columns(%args)
-
Fetches information about the columns of a table. This must work for all tables created by the driver. If the driver lists a table in
tables
, then it must be able to list columns for the table here.The arguments
%args
accepted are:Returns the column definition used to define the table.
- @indexes = $driver->indexes(%args)
-
Fetches information about the indexes of a table. This must work for all tables created by the driver. If the driver lists a table in
tables
, then it must be able to list columns for the table here.The arguments
%args
accepted are:Returns the index definition used to define the table.
- $row = $driver->first(%args)
-
Fetches the first row from a table.
The arguments
%args
accepted are:Returns the first record found according to the given
$handle
that was created with a call toopen_table
oropen_join
oropen_explicit_join
. The$row
returned is a hash reference where column names are the keys and their values are the values. This is called as an alternative tonext
to reset the "cursor" position to the top of the results.If no results are available, then this method will return
undef
. - $row = $driver->next(%args)
-
Fetches the next row from a table.
The arguments
%args
accepted are:Returns the next record found according to the given
$handle
that was created with a call toopen_table
oropen_join
open_explicit_join
. The$row
returned is a hash reference where column names are the keys and their values are the values. This moves the "cursor" position ahead one row.If no more results remain, then this method will return
undef
. An exception may be thrown if this method is called after eitherfirst
ornext
has already returnedundef
. - $value = $driver->sequence_value(%args)
-
$table, $column)
In the case of
AUTONUMBER
columns, this method returns the last inserted numeric value into a column. If no recent insert has been made or the column is not of typeAUTONUMBER
an exception will be thrown. Whether or not the last insert into a table is recent will depend upon back-end. However, it should generally be safe to assume that an insertion made since the current connection is recent. The arguments%args
accepted are:- $table
-
The table the
AUTONUMBER
column belongs to. - $column
-
The column of the table to fetch the last sequence value from.
Returns the last, recently inserted, sequence value for the column.
SEE ALSO
Persist, Persist::Source, Persist::Table, Persist::Join
AUTHOR
Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>
COPYRIGHT AND LICENSE
Copyright (c) 2003, Andrew Sterling Hanenkamp
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
* Neither the name of the Contentment nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.