NAME

DB::Ent - Database Entity Layer

SYNOPSIS

use DB::Ent;
$ef = DB::Ent->new();                      # entity factory
$au = $ef->mk(artist => "Peter Gabriel");  # create an artist
$cd = $au->mksub(CD => "Passion");         # create subordinate entity
$cd->attr(id => "0x0440F020") || die;      # set attributes
$cv = $dbe->mk(cover => "http://...");     # create a cover
$cd->rel($cv);                             # link to CD
$cd->rm();                                 # remove the CD

DESCRIPTION

This module presents an interface to an entity-centric database schema, providing all necessary methods to create, discover and manipulate entities and associated data.

The schema consists of 4 basic element storage types: 1) entities, 2) attributes, 3) relationships, and 4) extended attributes.

The terms entity and attribute are used here in accordance to the common definition used in relational database theory.

A differentiating factor between an entity and an attribute is that attributes serve no other purpose but to qualify an entity and cannot exist on their own. Entities may exist without qualifiers, requiring only a name.

Relationships of various kinds may be established between any two entities and these may be codified, enumerated or both.

Extended attributes comprise special datatypes and are typically used to store large format data.

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.

<return> = method-name <required> [optional = default] {alternate1 | alternate2}

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 name with an equal sign and the default value. When listing alternative parameters the syntax may nest brackets, e.g. the line below names that EITHER two required parameters may be passed OR a hash or hash reference.

{<val-1> <val-2> | hash[-ref]}

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

Return values

In general, methods return objects unless an error occurs in which case undef is returned. Certain methods specify their return value as ok which indicates a success flag (set to undef on failure). Upon encountering an error, the caller should consult the {err} and {errstr} fields in the object which contain a numeric error code and its corresponding description string.

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 <err>, if the context is scalar, only error code is returned.

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. mksub :: mk). Parameters to the method in question are placed after the template's last required parameter and before its first optional parameter.

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:

<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 returns undef for the object, followed by an error list.

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

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 information is passed, the variable DBE in the main namespace is assumed to contain a URL with the information. If this variable is empty, the environment variable of the same name is used. Any credential pieces not passed assume defaults.

DBED: Indicates the low-level driver to use. At present this value defaults to and can only be set to DBI. As other low level drivers are written, their names may be passed here.
URL: Specifies a connection URL of the form: proto://[user[:pass]@][host[/database]] where the items indicated in brackets are optional and which may be passed separately as described below.
proto: This key specifies the drivers to use for connecting to a datastore. The value will be passed through to the DBED and if not supplied, the DBED will select an appropriate default e.g. mysql.
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.
user: Specifies the account to use for logging into the datastore. If not provided the low-level driver will choose a default.
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.
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.

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.

mkuid: Specifies a code reference to be used in generating unique ids e.g. \MyModule::nextid. If no value is specified, unique strings are computed based on the md5 value of the canonicalised name.
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 DUPSQUIET, DUPSWARN, DUPSDIE (see section CONSTANTS at the end of this document).
upsert: This key allows the user to automatically overwrite existing entity attributes. For more information please see the the mk() method.
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.
trace: Setting this key to a filename will cause all commands issued to the datastore to be recorded in the file.

Virtual methods

The following methods may be overridden by the caller as desired:

dbcmd: This method is called with the full command about to be sent to the datastore. By default this method does nothing;
dberr: This key allows the caller to specify an error handler to use when low-level driver problems arise. The constants ERRWARN (current default) and ERRDIE may also be used to request that the default error handler die or merely warn upon errors;

<entity> = mk <entity-type> <entity-name> [attr-hashref]

Creates an entity with the given name and type and populates it with the attributes given in the optional hash reference. If the object already exists in the datastore no insertion is made and any attributes provided are discarded, unless the upsert flag is set in the entity factory, in which case all attributes specified are overwritten with the values supplied.

All entities have a unique id, normally calculated upon creation by the uid() method (see Configuration Parameters for the new() method). This default id is generated from a combination of the name and type of entity and may be overridden by specifying the uid key in the attribute hash. Additionally, to generate the uid using the current uid generator but with an alternative value, the key uidstr may be passed.

<entity[-list]> = ent <sel-hash-ref> [opts-hash[-ref]]

This method retrieves entities from the datastore.

Entities are returned according to selection criteria which are specified in a hash consisting of the attribute values being sought. Values in the selection hash may contain list references when multiple matches are desired. Additionally, hash values may contain the % wildcard to indicate partial matches. If no selection criteria are specified, the method will assume an id is being sought and takes the value of $_.

A hash of options intended to modify the return set may also be passed containing keys as outlined below:

sort: Specifies the attribute(s) to sort results by. A list reference may be passed when multiple values are desired; defaults to nm.

The return value consists of blessed objects, the number of which depends on the selection criteria. When a single object is found it is returned as a scalar, unless the calling context requests a list.

Note: The entities returned by this method contain only the most minimal of information i.e. that contained in the ent table. No attribute, relationship or other information is retrieved but these values may be got by calling specific methods for each. For a catalogue of such methods please refer to the METHODS - Entity Management section below.

<url> = cs

This method returns a url containing the connection information in use for the given datastore object. For information on the format of this string, please refer to the URL argument to the new() method.

METHODS - Entity Management

The methods listed below provide mechanisms for managing entity objects, their attributes and relationships. These methods can only be called on the objects generated by calls to entity-factory methods.

<ok> = rm [RELSONLY]

Removes an entity and all relationships to other entities. The method works recursively, destroying all dependencies, otherwise requested. For more information please refer to the documentation for the rmrel method.

mksub :: mk

Creates a sub-ordinate entity. The method must be called from an object generated by an entity factory and assumes such serves as the parent.

<ok> | <attr-hash[-ref]> = attr [<name> [value = $_] | attr-hashref]

Sets attributes for an entity.

Two parameter signatures are allowed; in the first form the method sets a single attribute; the second form allows for multiple attributes to be set. The return value in this case consists of an ok value.

Attributes are created whenever they do not exist in the datastore but when already present, their values are respected, unless the upsert flag in the entity factory is set.

The current value of an attribute may be updated via a calculation by passing a code reference as a value. The code-ref will be called with the value of $_ set to the current attribute's value and will be responsible for returning the new value, e.g. to increment a value the following may be used:

$self->attr(count => sub { $_++ });

<hash[-ref]> = attrs [attr-listref] [DTT]

Retrieves the attributes of an identity. Specific attributes may be requested by passing their names in a list reference. If the constant DTT is passed, datatype information will be embedded in the keys of the return hash.

The attributes retrieved (and returned) are also embedded internally into the object.

<ok> = rmattr [attr-list]

Removes an entity's attributes. If a list of attribute names is provided, only those attributes are removed.

<ok> = rel <entity[-listref]> [options-hashref]

Creates a relationship between the current entity and a list of given entities. Relationshps are always enumerated but may also be codified, as indicated in the options hash optionally passed. Valid keys for this hash are as follows:

type: Specifies the type of relationship. If no type is specified, the relationship is not considered to be codified.
nn: Passing a value with this key cements the relationship number between two entities. Generally there is no good reason to want this, and as attempting to establish a relationship between to entities with the same numeric value (within a given relationship-type (code)) will cause an error, abstention from use of this key is recommended. If not specified, its value is calculated as the next number available.
unique: If this key is set to true, the system will enforces a single relationship between the two entities (regardless of relationship type). By default this value is false.
parent: Most commonly the caller will intend to create child relationships between the current entity and the passed list of subordinate entities. At times however, it may be necessary to reverse the sense of this assignment, making each of the entities in the list, the parent of the current entity. Setting this flag to true allows for that to happen.

<entity-list[-ref]> = rels [opts-hash[-ref]]

Returns a list of entities related to the current entity. Please note that these values get cached inside the object as either _parents_ or _children_.

The options hash specifies behaviour as follows:

cd: The caller may limit the entities returned by relationship code. The value passed may be either a scalar or a list reference.
parent: If this flag is set, instead of returning an entity's children, the parents are returned.

<ok> = rmrel [ents => listref, relsonly => 1]

Removes an entity's relationships with the given list of entities by removing these from the datastore. Please note that this process works recursively, removing children's children to any level, thus effectively pruning the relationship tree connected at the current entity. If the list passed is empty, all children are removed.

If the flag relsonly is set, the method only severs the entity's relationships with other entities without destroying these.

<hash-[ref]> = args [hash, hash-ref, ...]

This function conveniently parses arguments passed to a method. It should be called in non OO style without arguments and returns a hash or hash reference (depending on context) with the values.

- exempli gratia -

sub tst {
    my $args = &DB::Ent::args;
    print $args->{key};
    }

CONSTANTS

A number of constants are used by the various methods; these are typically access directly from the package e.g. $DB::Ent::DTT. A description of each follows:

DUPSQUIET: specifies that entity creation failures owning to duplicate keys should be silently ignored.
DUPSWARN: specifies duplicate key violations should issue warnings.
DUPSDIE: specifies duplicate key violations should cause the process to die.
ERRWARN: specifies that only warnings should be issued when encountering errors.
ERRDIE: specifies that the process should die when errors are found.
RELSONLY: #FIXME
DTT: #FIXME

DRIVERS

Drivers are modules that provide low-level primitives to access specific datastores. Please note that the entity/attribute nomenclature may not map directly to a table/column, file/line, record/field, row/cell or other metaphor supported by the underlying datastore.

At present only a DBI driver exists but a published API (see man page for DB::Ent::DBI) exists to allow developers to write other drivers.

AUTHOR

Erick Calder <ecalder@cpan.org>

SUPPORT

For help and thank you notes, e-mail the author directly. To report a bug, submit a patch or add to our wishlist please visit the CPAN bug manager at: http://rt.cpan.org

AVAILABILITY

The latest version of the tarball, RPM and SRPM may always be found at: http://perl.arix.com/ Additionally the module is available from CPAN.

LICENCE AND COPYRIGHT

This utility is free and distributed under GPL, the Gnu Public License. A copy of this license was included in a file called LICENSE. If for some reason, this file was not included, please see http://www.gnu.org/licenses/ to obtain a copy of this license.

NAME

DB::Ent::DBI - DBI Driver for DB::Ent

SYNOPSIS

use DB::Ent::DBI;
$dbx = DB::Ent::DBI->new();
$dbx->ins();
$dbx->del();
$dbx->upd();

DESCRIPTION

This module provides a DBI-based driver for the DB::Ent schema abstraction layer and serves as a guideline for other driver development efforts by documenting the API.

Please note that for this driver the choice of nomenclature consists of table/column/row. Also, some methods return <err>; this is a list consisting of a numeric error code, followed by its human-legible corresponding string.

<db, err> = new [pass-through]

Used to generate a datastore connection object. Any optional arguments passed may be used to create and configure the connection. The method returns a list containing a blessed object, a numeric error code, and a human legible error string.

If the object is set to undef the caller should check the error values, else the returned object may be used to access the methods listed below:

<ok> = init

Used to create an entity schema this method must be called with extreme care as it will first destroy an existing schema, including all data. Before this method may be called, a connection to the datastore must be established.

Typically it is not necessary for users to call this method directly since the new method will call it if it detects that the datastore has not been initialised.

The storage element types (in the nomenclature of this driver these are database tables) created are named: ent, attr, rel, and xattr. The nm parameter to the various methods offered by this module must receive one of these values.

This method takes no arguments and returns a success flag.

<id> = ins <nm> <attr-hashref> [filt-hashref]

Creates a new entry of the type indicated by the first argument passed (see docs for the init() method above for a review of valid names). Attributes must be passed in a hash reference and must match those allowed by the element type.

The return value consists of the id of the new entry; in case of failure error information is returned.

Note: For signature compatibility with upd(), this method accepts a filter hash reference whose keys are added to the attr-hashref. This makes for easy upserts!

<rows> = upd <nm> <attr-hashref> [filt-hashref]

This method updates an entry of the type specified by the nm parameter (see docs for the init() method above for a review of valid names). The data updated is provided as a hash reference of attribute name/value pairs. Additionally a filter may be provided (also as a hash reference of attribute name/value pairs) which limits the update operation to only those entries specified (in table parlance, this represents a row selector i.e. an sql where clause).

The return value indicates the number of rows affected.

<ok> = del <nm> <attr-hashref>

Deletes any entity that matches the given list of attributes' values. Instead of not passing any attributes in the hash reference in order to delete all items in a table, pass the key ALL set to 1 - this is to prevent costly mistakes.

<hashref-list> = sel <criteria-hash[-ref]>

Returns a list of hash references containing entities that match the selection criteria. The values in the hash to this method may contain list references and wildcards are allowed within scalars for incomplete matching.

<attr-list> = def <entity-type>

Returns a list of attributes associated with a particular entity type.

AUTHOR

Erick Calder <ecalder@cpan.org>

SUPPORT

For help and thank you notes, e-mail the author directly. To report a bug, submit a patch or add to our wishlist please visit the CPAN bug manager at: http://rt.cpan.org

AVAILABILITY

The latest version of the tarball, RPM and SRPM may always be found at: http://perl.arix.com/ Additionally the module is available from CPAN.

LICENCE AND COPYRIGHT

This product is free and distributed under the Gnu Public License (GPL). A copy of this license was included in this distribution in a file called LICENSE. If for some reason, this file was not included, please see http://www.gnu.org/licenses/ to obtain a copy of this license.

$Id: Ent.pm,v 1.63 2003/06/24 03:58:11 ekkis Exp $

To install DB::Ent, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DB::Ent

CPAN shell

perl -MCPAN -e shell
install DB::Ent

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

SYNTAX

Parameters

Return values

Signature templates

METHODS

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

<entity> = mk <entity-type> <entity-name> [attr-hashref]

<entity[-list]> = ent <sel-hash-ref> [opts-hash[-ref]]

<url> = cs

METHODS - Entity Management

<ok> = rm [RELSONLY]

mksub :: mk

<ok> | <attr-hash[-ref]> = attr [<name> [value = $_] | attr-hashref]

<hash[-ref]> = attrs [attr-listref] [DTT]

<ok> = rmattr [attr-list]

<ok> = rel <entity[-listref]> [options-hashref]

<entity-list[-ref]> = rels [opts-hash[-ref]]

<ok> = rmrel [ents => listref, relsonly => 1]

<hash-[ref]> = args [hash, hash-ref, ...]

CONSTANTS

DRIVERS

AUTHOR

SUPPORT

AVAILABILITY

LICENCE AND COPYRIGHT

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

<db, err> = new [pass-through]

<ok> = init

<id> = ins <nm> <attr-hashref> [filt-hashref]

<rows> = upd <nm> <attr-hashref> [filt-hashref]

<ok> = del <nm> <attr-hashref>

<hashref-list> = sel <criteria-hash[-ref]>

<attr-list> = def <entity-type>

AUTHOR

SUPPORT

AVAILABILITY

SEE ALSO

LICENCE AND COPYRIGHT

Module Install Instructions