| 1 |
PGObject |
| 2 |
|
| 3 |
PGObject is a module intended to be a base for object class frameworks which map |
| 4 |
PostgreSQL stored procedures to object methods in a relatively loosely coupled |
| 5 |
way. PGObject provides the bare-bones infrastructure required to make it |
| 6 |
happen. This module is primarily of interest to individuals writing such |
| 7 |
frameworks, and very little in here is likely to be used directly outside of |
| 8 |
such frameworks. |
| 9 |
|
| 10 |
The initial release, 1.0.0 is based on our six years of experience using |
| 11 |
essentially the same approach in LedgerSMB (starting with the beginnings of the |
| 12 |
1.3 codebase in 2007). This release is largely based on the code I wrote for |
| 13 |
LedgerSMB but it cleans up and refactors such work based on the lessons learned. |
| 14 |
|
| 15 |
INSTALLATION |
| 16 |
|
| 17 |
To install this module, run the following commands: |
| 18 |
|
| 19 |
perl Makefile.PL |
| 20 |
make |
| 21 |
make test |
| 22 |
make install |
| 23 |
|
| 24 |
SUPPORT AND DOCUMENTATION |
| 25 |
|
| 26 |
After installing, you can find documentation for this module with the |
| 27 |
perldoc command. |
| 28 |
|
| 29 |
perldoc PGObject |
| 30 |
|
| 31 |
You can also look for information at: |
| 32 |
|
| 33 |
RT, CPAN's request tracker (report bugs here) |
| 34 |
https://rt.cpan.org/NoAuth/Bugs.html?Dist=PGObject |
| 35 |
|
| 36 |
MetaCPAN |
| 37 |
https://metacpan.org/dist/PGObject |
| 38 |
|
| 39 |
|
| 40 |
WRITING PGOBJECT-AWARE PERL CLASSES |
| 41 |
|
| 42 |
One of the powerful features of PGObject is the ability to declare methods in |
| 43 |
types which can be dynamically detected and used to serialize data for query |
| 44 |
purposes. Objects which contain a pgobject_to_db(), that method will be called |
| 45 |
and the return value used in place of the object. This can allow arbitrary |
| 46 |
types to serialize themselves in arbitrary ways. |
| 47 |
|
| 48 |
For example a date object could be set up with such a method which would export |
| 49 |
a string in yyyy-mm-dd format. An object could look up its own definition and |
| 50 |
return something like : |
| 51 |
|
| 52 |
{ cast => 'dbtypename', value => '("A","List","Of","Properties")'} |
| 53 |
|
| 54 |
If a scalar is returned that is used as the serialized value. If a hashref is |
| 55 |
returned, it must follow the type format: |
| 56 |
|
| 57 |
type => variable binding type, |
| 58 |
cast => db cast type |
| 59 |
value => literal representation of type, as intelligible by DBD::Pg |
| 60 |
|
| 61 |
|
| 62 |
WRITING TOP-HALF OBJECT FRAMEWORKS FOR PGOBJECT |
| 63 |
|
| 64 |
PGObject is intended to be the database-facing side of a framework for objects. |
| 65 |
The intended structure is for three tiers of logic: |
| 66 |
|
| 67 |
1. Database facing, low-level API's |
| 68 |
2. Object management modules |
| 69 |
3. Application handlers with things like database connection management. |
| 70 |
|
| 71 |
By top half, we are referring to the second tier. The third tier exists in the |
| 72 |
client application. |
| 73 |
|
| 74 |
The PGObject module provides only low-level API's in that first tier. The job |
| 75 |
of this module is to provide database function information to the upper level |
| 76 |
modules. |
| 77 |
|
| 78 |
We do not supply type information, If your top-level module needs this, please |
| 79 |
check out https://code.google.com/p/typeutils/ which could then be used via our |
| 80 |
function mapping APIs here. |
| 81 |
|
| 82 |
LICENSE AND COPYRIGHT |
| 83 |
|
| 84 |
COPYRIGHT (C) 2013-2014 Chris Travers |
| 85 |
COPYRIGHT (C) 2014-2021 The LedgerSMB Core Team |
| 86 |
|
| 87 |
Redistribution and use in source and compiled forms with or without |
| 88 |
modification, are permitted provided that the following conditions are met: |
| 89 |
|
| 90 |
* Redistributions of source code (Perl) must retain the above |
| 91 |
copyright notice, this list of conditions and the following disclaimer as the |
| 92 |
first lines of this file unmodified. |
| 93 |
|
| 94 |
* Redistributions in compiled form must reproduce the above copyright |
| 95 |
notice, this list of conditions and the following disclaimer in the |
| 96 |
source code, documentation, and/or other materials provided with the |
| 97 |
distribution. |
| 98 |
|
| 99 |
THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND |
| 100 |
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 101 |
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| 102 |
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR |
| 103 |
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
| 104 |
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| 105 |
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON |
| 106 |
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 107 |
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 108 |
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |