NAME

App::Dochazka::REST::Model::Shared - functions shared by several modules within the data model

SYNOPSIS

    use App::Dochazka::REST::Model::Shared;

    ...

EXPORTS

This module provides the following exports:

• canonicalize_ts

  Run timestamp by PostgreSQL

• canonicalize_tsrange

  Run tsrange by PostgreSQL

• cud

  Create, Update, Delete -- for single-record statements only

• decode_schedule_json

  Given JSON string, return corresponding hashref

• load

  Load/Fetch/Retrieve a single datamodel object

• load_multiple

  Load/Fetch/Retrieve multiple datamodel objects

• noof

  Get total number of records in a data model table

• priv_by_eid

• schedule_by_eid

• select_single

  Run an arbitrary SELECT that returns 0 or 1 records

• select_set_of_single_scalar_rows

FUNCTIONS

canonicalize_ts

Given a string that might be a timestamp, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS timestamptz )

canonicalize_tsrange

Given a string that might be a tsrange, "canonicalize" it by running it through the database in the SQL statement:

    SELECT CAST( ? AS tstzrange )

Returns an App::CELL::Status object. If the status code is OK, then the tsrange is OK and its canonicalized form is in the paylmad. Otherwise, some kind of error occurred, as described in the status object.

make_test_exists

Returns coderef for a function, 'test_exists', that performs a simple true/false check for existence of a record matching a scalar search key. The record must be an exact match (no wildcards).

Takes one argument: a type string $t which is concatenated with the string 'load_by_' to arrive at the name of the function to be called to execute the search.

The returned function takes a single argument: the search key (a scalar value). If a record matching the search key is found, the corresponding object (i.e. a true value) is returned. If such a record does not exist, 'undef' (a false value) is returned. If there is a DBI error, the error text is logged and undef is returned.

cud

Attempts to Create, Update, or Delete a single database record. Takes the following PARAMHASH:

• conn

  The DBIx::Connector object with which to gain access to the database.

• eid

  The EID of the employee originating the request (needed for the audit triggers).

• object

  The Dochazka datamodel object to be worked on.

• sql

  The SQL statement to execute (should be INSERT, UPDATE, or DELETE).

• attrs

  An array reference containing the bind values to be plugged into the SQL statement.

Returns a status object.

Important note: it is up to the programmer to not pass any SQL statement that might affect more than one record.

decode_schedule_json

Given JSON string representation of the schedule, return corresponding HASHREF.

load

Load a database record into an object based on an SQL statement and a set of search keys. The search key must be an exact match: this function returns only 1 or 0 records. Call, e.g., like this:

    my $status = load( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 44 ]
    ); 

The status object will be one of the following:

• 1 record found

  Level OK, code DISPATCH_RECORDS_FOUND, payload: object of type 'class'

• 0 records found

  Level NOTICE, code DISPATCH_NO_RECORDS_FOUND, payload: none

• Database error

  Level ERR, code DOCHAZKA_DBI_ERR, text: error message, payload: none

load_multiple

Load multiple database records based on an SQL statement and a set of search keys. Example:

    my $status = load_multiple( 
        conn => $conn,
        class => __PACKAGE__, 
        sql => $site->DOCHAZKA_SQL_SOME_STATEMENT,
        keys => [ 'rom%' ] 
    ); 

The return value will be a status object, the payload of which will be an arrayref containing a set of objects. The objects are constructed by calling $ARGS{'class'}->spawn

For convenience, a 'count' property will be included in the status object.

noof

Given a DBIx::Connector object and the name of a data model table, returns the total number of records in the table.

    activities employees intervals locks privhistory schedhistory
    schedintvls schedules

On failure, returns undef.

priv_by_eid

Given an EID, and, optionally, a timestamp, returns the employee's priv level as of that timestamp, or as of "now" if no timestamp was given. The priv level will default to 'passerby' if it can't be determined from the database.

schedule_by_eid

Given an EID, and, optionally, a timestamp, returns the SID of the employee's schedule as of that timestamp, or as of "now" if no timestamp was given.

_st_by_eid

Function that 'priv_by_eid' and 'schedule_by_eid' are wrappers of.

select_single

Given a DBIx::Connector object in the 'conn' property, a SELECT statement in the 'sql' property and, in the 'keys' property, an arrayref containing a list of scalar values to plug into the SELECT statement, run a selectrow_array and return the resulting list.

Returns a standard status object (see load routine, above, for description).

get_history

This function takes a number of arguments. The first two are (1) a DBIx::Connector object and (2) a SCALAR argument, which can be either 'priv' or 'schedule'.

Following these there is a PARAMHASH which can have one or more of the properties 'eid', 'nick', and 'tsrange'. At least one of { 'eid', 'nick' } must be specified. If both are specified, the employee is determined according to 'eid'.

The function returns the history of privilege level or schedule changes for that employee over the given tsrange, or the entire history if no tsrange is supplied.

The return value will always be an App::CELL::Status object.

Upon success, the payload will be a reference to an array of history objects. If nothing is found, the array will be empty. If there is a DBI error, the payload will be undefined.

select_set_of_single_scalar_rows

Given DBIx::Connector object, an SQL statement, and a set of keys to bind into the SQL statement, assume that the statement can return 0-n records and that each record consists of a single field that must fit into a single scalar value.

AUTHOR

Nathan Cutler, <presnypreklad@gmail.com>

cpanm App::Dochazka::REST

perl -MCPAN -e shell
install App::Dochazka::REST