pjs/webtools/PLIF/PLIF

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.