view release on metacpan or  search on metacpan

Ent.pm  view on Meta::CPAN

package DB::Ent;

use 5.006;
use strict;
use warnings;

use Exporter;
use vars qw/@ISA/;

our $VERSION = substr q$Revision: 1.63 $, 10;
sub OK { 1; }

### TODO ###

# new(): allow empty values for attributes

# --- exported module interface -----------------------------------------------

=head1 SYNTAX

Methods are listed by declaring their signatures, the general format of which consists of a return value followed by an equal sign and the method name, followed by a list of parameters, e.g.

I<E<lt>returnE<gt> = method-name E<lt>requiredE<gt> [optional = default] {alternate1 | alternate2}>

=head2 Parameters

Required parameters are named within angles whilst optional parameters within brackets; alternative parameters use braces separated by pipes.  Whenever optional parameters are specified, the default value may be represented by following the parameter...

I<{E<lt>val-1E<gt> E<lt>val-2E<gt> | hash[-ref]}>

Please note that failing to pass required arguments in a method call results in program death.

=head2 Return values

In general, methods return objects unless an error occurs in which case I<undef> is returned.  Certain methods specify their return value as I<ok> which indicates a success flag (set to I<undef> on failure).  Upon encountering an error, the caller sh...

Return values are typically context-sensitive and may also be sensitive to the argument signature.  When different return values may be expected, these appear separated with pipes.  When the return value is an I<E<lt>errE<gt>>, if the context is scal...

=head2 Signature templates

Whenever the syntax for a method is indicated with a double colon, it specifies that the signature for the current method follows that of a template method which is indicated following the double colon (e.g. I<mksub :: mk>).  Parameters to the method...

=cut

# --- entity factory methods --------------------------------------------------

=head1 METHODS

The module presents an object-oriented interface divided into two major functional groups: entity-factory methods, and entity-management methods.

Entity factory methods concern the binding of perl objects to datastore items.  This includes insertion, discovery and retrieval methods as well as entity-factory configuration methods.  This category includes the following:

=head2 <entity-factory> <err> = new [hash[-ref]]

Before entities can be created and managed, an entity factory must be instantiated.  This method returns such an object and receives two kinds of parameters: connection parameters, and configuration parameters.  If any error is encountered the method...

Parameters are all passed as a hash or hash reference whose keys are described below:

I<Connection Parameters>

To establish a connection to a datastore, the caller must pass credentials.  These may be passed either in URL syntax and/or as separate keys.  Any information passed separately overrides the appropriate value in the URL.  If no connection informatio...

=over

=item DBED

Indicates the low-level driver to use.  At present this value defaults to and can only be set to C<DBI>.  As other low level drivers are written, their names may be passed here.

=item URL

Specifies a connection URL of the form: I<proto://[user[:pass]@][host[/database]]> where the items indicated in brackets are optional and which may be passed separately as described below.

=item proto

This key specifies the drivers to use for connecting to a datastore.  The value will be passed through to the I<DBED> and if not supplied, the DBED will select an appropriate default e.g. C<mysql>.

=item host

This indicates the name or IP address of the server hosting the datastore.  If not provided, the low level driver will choose a default.

=item user

Specifies the account to use for logging into the datastore.  If not provided the low-level driver will choose a default.

=item password

Necessary when security measures have been placed on the account in use.  Passwords are provided in plain-text.  If not provided, default is left to the low-level driver.

=item database

This key specifies the namespace within the server to use.  If not specified, a default home will be used.  Please note however that not all database systems either have a namespace concept, nor a default value for it.

=back

I<Configuration Parameters>

The following keys define various behaviours for the entity factory.  The values are stored as keys in the object itself and may be manipulated directly.

=over

=item mkuid

Specifies a code reference to be used in generating unique ids e.g. I<\MyModule::nextid>.  If no value is specified, unique strings are computed based on the md5 value of the canonicalised name.

=item dups

The duplicates flag indicates the action to take when db insert fails because an entity already exists.  The value may be set to any of the following constants B<DUPSQUIET>, B<DUPSWARN>, B<DUPSDIE> (see section B<CONSTANTS> at the end of this documen...

=item upsert

This key allows the user to automatically overwrite existing entity attributes.  For more information please see the the B<mk()> method.

=item debug

Setting this key allows for debugging output to be produced by the module.  A 1 is the minimum required with increased verbosity resulting from larger values.  By default no debugging output is generated.

=item trace

Setting this key to a filename will cause all commands issued to the datastore to be recorded in the file.

=back