136 lines
5.0 KiB
Plaintext
136 lines
5.0 KiB
Plaintext
PLIF: Program Logic Insulation Framework
|
|
========================================
|
|
|
|
Overview
|
|
--------
|
|
|
|
PLIF is based around the idea of services. Some more text really
|
|
should go here, don't you think?
|
|
|
|
Note that in this document, the term "provide a service" is used to
|
|
mean what some people term "implement an interface". The terms are
|
|
interchangeable. Due to Perl's amorphous nature, I found the term
|
|
"interface" to be a bit inappropriate, in my opinion it has
|
|
connotations of strictness that are not really applicable to Perl...
|
|
|
|
|
|
Services
|
|
--------
|
|
|
|
The following services (also termed 'interfaces') have meaning in the
|
|
basic PLIF design:
|
|
|
|
input - implements all of the Input API
|
|
input.verify - provides a verifyInput() method
|
|
output.<protocol> - implements all of the Output API
|
|
dataSource.<dataSet> - provides a data source for dataSet
|
|
dataSource.setupAware - knows how to set up the database
|
|
|
|
|
|
input semantics
|
|
---------------
|
|
|
|
These are not simple. See the example implementations.
|
|
|
|
|
|
input.verify semantics
|
|
----------------------
|
|
|
|
If you provide input.verify, then you should expect to get called each
|
|
time a set of input needs validating. Input validation means stuff
|
|
like checking that an e-mail's format is correct, or authentication
|
|
the user if they have tried to log in, or whatever.
|
|
|
|
When your "verifyInput()" method is called, you should return nothing
|
|
(not even undef) if everything is ok, and a reference to an object
|
|
that has a reportInputVerificationError() method if something went
|
|
wrong. If you return yourself (i.e., if you implement both methods
|
|
being discussed here), remember that there is no guarentee that you
|
|
will be destructed before the next time you are called, so don't
|
|
design your verifyInput() method in a way that assumes you won't have
|
|
pre-existing state. Also, since there is no guarentee that your
|
|
reportInputVerificationError() method will be called, don't hold on to
|
|
any references like, say, input. If you do you might end up leaking
|
|
memory, which we don't want!
|
|
|
|
Verifiers will be called in the order they were registered. If any
|
|
fail (i.e., return an object) then the verification loop is aborted.
|
|
For this reason, you should register verifiers in the order that they
|
|
are most likely to fail so that the loop ends in the shortest time.
|
|
|
|
If successful, the verifiers should initialise any objects (like user
|
|
objects from successful authentication) using $app->addObject(). The
|
|
first object claiming to provide the 'session' service is the object
|
|
that will be passed (by default) to output services.
|
|
|
|
|
|
|
|
output.* semantics
|
|
------------------
|
|
|
|
Output uses the following kind of command flow through services:
|
|
|
|
logic
|
|
|
|
|
+---------+---------+
|
|
| |
|
|
output.<protocol> output.generic
|
|
|
|
|
+------------+------------+
|
|
| |
|
|
string.expander.<string> string.expander
|
|
| |
|
|
+------------+------------+
|
|
|
|
|
output.generic.<protocol>
|
|
|
|
|
|
string.expander semantics
|
|
-------------------------
|
|
|
|
These services provide and |expand| function that takes four
|
|
arguments: the application object, the name of the protocol, the name
|
|
of the string to expand, and the data hash. The function should return
|
|
an opaque string.
|
|
|
|
|
|
dataSource.setupAware
|
|
---------------------
|
|
|
|
Most data sources are expected to provide the "dataSource.setupAware"
|
|
service, which basically means that they have a setup method that does
|
|
whatever is required to the databases. We should also introduce some
|
|
uninstall awareness, some default data populatingness, and stuff...
|
|
|
|
|
|
Class Tree
|
|
----------
|
|
CORE
|
|
|
|
|
+------+------------+-------------------+
|
|
| | | |
|
|
PLIF ... MagicPipingArray MagicSelectingArray
|
|
|
|
|
+---------+-----------------------+--------------------+
|
|
Controller | |
|
|
| Service DBI
|
|
Program | (ResultsFrame)
|
|
| |
|
|
Application +--------+-------+-----+-----+-------+-------+--------+
|
|
| | | | | | | |
|
|
... DataSource COSES DataBase Input Object Output StdOut
|
|
| | | | | (Outputter)
|
|
+--------+------+----+ +--+--+ Arguments ... +--+--+
|
|
| | | | | | | |
|
|
... Configuration Strings CfgFile DBI +-----+-----+ ... Generic
|
|
| | | |
|
|
MySQL CommandLine CGI Default
|
|
|
|
|
|
|
|
Contributions
|
|
-------------
|
|
|
|
Please make sure you read the STYLEGUIDE if you want to consider
|
|
writing code.
|