/ 
persist-0.5.3
/ Persist

NAME

Persist - This class contains constants and helpers for the Persist framework

SYNOPSIS

use Persist qw(:constants);

# ... use 'em ...

DESCRIPTION

If you are looking for usage information related to Persist the best starting place is Persist::Source.

This class contains constants and help functions for the Persist framework. There are currently three sets of constants: types, indexes, and orders. The helper functions are intended for use by the drivers and are described further on below.

TYPES

The types are:

VARCHAR

Limited length variable length string. Use of this type should be following by a single numeric value which is the maximum number of characters that should be used in values stored in this type of column. The maximum limit of data that may be stored in a VARCHAR will depend greatly upon the implementation. It is suggested that the drivers try to use a type that will allow up to 5000 characters to be stored.

INTEGER

Integer value type. Takes no arguments and should store any 32-bit integer value.

AUTONUMBER

Integer sequence type. This column provides a unique default value upon insertion. It takes no arguments and should be type equivalent to INTEGER. Columns with this type should not be explicitly set during insertion or update. The driver may choose to make such attempts exceptional.

BOOLEAN

Boolean value that is true (1) or false (0) or NULL (undef). It takes no arguments. Some database backends will not support this directly, but it should always be simulated by the driver.

REAL

A real number value. This should be used for Perl's floating point values. It takes no arguments and database should try to support values up to double precision floating point values and be at least as accurate.

TIMESTAMP

A date/time value. Values of this type will be represented in Perl as an object of the DateTime package. When represented as a string, it should be in ISO 8601 format.

See the documentation of DateTime for details.

INDEXES

The indexes are:

PRIMARY

This is the key that is used to uniquely identify the row. Duplicates should not be allowed and there should always be a value stored in this column (that is, it should never be NULL/undef). All tables must exactly one primary index.

This takes an array reference naming all the columns that are in the index. For example,

[ PRIMARY, [ 'someid', 'name' ] ]
UNIQUE

This notes that the column(s) may be used to unique identify the row, but is not the primary index.

This takes an array reference naming all the columns that are in the index. For example,

[ UNIQUE, [ 'someid', 'name' ] ]

This links two tables by one or more columns.

This index takes three arguments. The first is an array reference naming all the local columns that reference the other table. The second is the name of the referenced table. The third is the an array reference naming the foreign columns that are referenced. The number of columns specified locally and foreign should be the same.

For example,

[ LINK, [ 'someid', 'name' ], 'another_table', [ 'anoid', 'name' ] ]

ORDERS

The orders are used in parameter lists passed to filtering methods. These parameters are used to specify in which order records are to be returned. These constants are then inserted as modifiers after a column name to tell the system that the columns should be sorted in ascending or descending order. By default, orders are always in ascending order, so specifying the ASC or ASCENDING constants are redundant, but sometimes helpful.

ASC =item ASCENDING

These constants signal that the previous column in a list of columns passed to the "order" parameter of a filtering method are supposed to be sorted in ascending order--the default.

DESC =item DESCENDING

These constants signal that the previous column in a list of columns passed to the "order" parameter of a filtering method are supposed to be sorted in descending, rather than ascending, order.

DRIVER HELPERS

This section is only of interest to driver implementors. The following helper routines have been written to help with driver implementation. They may be imported each by name or both by ':driver_help'.

These were added because the croak and carp methods provided by the Carp package are a little week for our needs. The Carp methods will note errors in the first caller outside of the current package in the call-stack (I think). These, will note errors in the first caller outside of Persist packages.

The important difference is that a driver error will be reported in user code rather in the Persist package using the driver. A great aid to debugging.

croak @msg

This method dies with a message and notes the package and line of the first caller outside of the Persist framework.

carp @msg

This method warns with a message and notes the package and line of the first caller outside of the Persist framework.

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.