App::Dochazka::REST::Model::Employee - Employee data model
Version 0.115
Employee data model
use App::Dochazka::REST::Model::Employee; ...
A description of the employee data model follows.
At the database level, App::Dochazka::REST needs to be able to distinguish one employee from another. This is accomplished by the EID. All the other fields in the employees table are optional.
App::Dochazka::REST
employees
The employees database table is defined as follows:
CREATE TABLE employees ( eid serial PRIMARY KEY, nick varchar(32) UNIQUE, fullname varchar(96) UNIQUE, email text UNIQUE, passhash text, salt text, remark text, stamp json )
The Employee ID (EID) is Dochazka's principal means of identifying an employee. At the site, employees will be known by other means, like their full name, their username, their user ID, etc. But these can and will change from time to time. The EID should never, ever change.
The nick field is intended to be used for storing the employee's username. While storing each employee's username in the Dochazka database has undeniable advantages, it is not required - how employees are identified is a matter of site policy, and internally Dochazka does not use the nick to identify employees. Should the nick field have a value, however, Dochazka requires that it be unique.
nick
Dochazka does not maintain any history of changes to the employees table.
The full_name and email fields must also be unique if they have a value. Dochazka does not check if the email address is valid.
full_name
email
# # FIXME: NOT IMPLEMENTED depending on how App::Dochazka::REST is configured, # these fields may be read-only for employees (changeable by admins only), or # the employee may be allowed to maintain their own information.
The passhash and salt fields are optional. See "AUTHENTICATION" for details.
# FIXME
Individual employees are represented by "employee objects". All methods and functions for manipulating these objects are contained in App::Dochazka::REST::Model::Employee. The most important methods are:
constructor (spawn)
basic accessors (eid, fullname, nick, email, passhash, salt, remark)
privilege accessor (priv)
schedule accessor (schedule)
reset (recycles an existing object by setting it to desired state)
insert (inserts object into database)
update (updates database to match the object)
delete (deletes record from database if nothing references it)
load_by_eid (loads a single employee into the object)
load_by_nick (loads a single employee into the object)
App::Dochazka::REST::Model::Employee also exports some convenience functions:
nick_exists (given a nick, return true/false)
For basic employee object workflow, see the unit tests in t/004-employee.t.
employee
t/004-employee.t
This module provides the following exports:
Employee constructor. Does not interact with the database directly, but stores database handle for later use. Takes PARAMHASH with required parameter 'dbh' (database handle). Optional parameter: PARAMHASH containing definitions of any of the attributes listed in the 'reset' method.
Instance method. Resets object, either to its primal state (no arguments) or to the state given in PARAMHASH.
Basic accessor methods for all the fields of employees table. These functions return whatever value happens to be associated with the object, with no guarantee that it matches the database.
Accessor method.
Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::priv_by_eid N.B.: for this method to work, the 'eid' attribute must be populated
Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::schedule_by_eid N.B.: for this method to work, the 'eid' attribute must be populated
Instance method. Takes the object, as it is, and attempts to insert it into the database. On success, overwrites object attributes with field values actually inserted. Returns a status object.
Instance method. Assuming that the object has been prepared, i.e. the EID corresponds to the employee to be updated and the attributes have been changed as desired, this function runs the actual UPDATE, hopefully bringing the database into line with the object. Overwrites all the object's attributes with the values actually written to the database. Returns status object.
Instance method. Assuming the EID really corresponds to the employee to be deleted, this method will execute the DELETE statement in the database. It won't succeed if there are any records anywhere in the database that point to this EID. Returns a status object.
Attempts to load employee from database, by the nick provided in the argument list, which must be an exact match. If the employee is found, it is loaded into a temporary hash. If called as a class method, a new employee object is spawned and populated with the values in the temporary hash. If called on an existing object, overwrites whatever might have been there before.
In general, this function returns the same status object as it gets from _load.
Analogous method to "load_by_nick".
Fetches employee from database, by eid or nick, into a hashref. The search key (eid or nick) must be an exact match: this function returns only 1 or 0 records. Takes one of the two following PARAMHASHes:
nick => $nick eid => $eid
Returns one of three possible status objects:
success: level OK, code DISPATCH_RECORDS_FOUND, hashref in payload failure: level OK, code DISPATCH_NO_RECORDS_FOUND DBI err: level ERR, code DOCHAZKA_DBI_ERR
The following functions are not object methods.
Class method. Select multiple employees by nick. Returns a status object. If records are found, they will be in the payload (reference to an array of expurgated employee objects).
1. make deep copy of the object, 2. unbless it, 3. return it
The following functions are exported and are not called as methods.
Simple true/false check if a nick exists. If the nick exists, returns the corresponding employee object (i.e. a true value). If the nick does not exist, returns 'undef' (a false value). If there is a DBI error, the function dies.
Analogous function to "nick_exists".
Nathan Cutler, <presnypreklad@gmail.com>
<presnypreklad@gmail.com>
To install App::Dochazka::REST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Dochazka::REST
CPAN shell
perl -MCPAN -e shell install App::Dochazka::REST
For more information on module installation, please visit the detailed CPAN module installation guide.