gecko-dev/webtools/PLIF/PLIF
ian%hixie.ch 1a231e506c Correcting minor typo (extraneous ')'s). 2001-10-04 16:09:32 +00:00
..
DataSource Added a string data source which gets the strings from a file instead of from the database, useful as a fallback. 2001-09-09 19:19:05 +00:00
Database Added a comment clarification. 2001-09-09 19:06:13 +00:00
DatabaseHelper Corrected the SQL for 'SHOW COLUMNS FROM' so that it actually works... 2001-09-09 19:21:17 +00:00
Input Some more minor corrections to get it to run as well as compile... (removes some XXX comments and adds some error checking) 2001-06-03 15:27:16 +00:00
Output Cached the SMTP object to improve performance. 2001-09-19 18:05:28 +00:00
Service Correcting minor typo (extraneous ')'s). 2001-10-04 16:09:32 +00:00
Application.pm * fixed the methodMissing() method so that it actually is possible to use it to do method dispatching; 2001-05-06 06:26:24 +00:00
Controller.pm Corrected an oversight in the service instance creation code: if a service acts as both a service instance and a normal service, it needs a special constructor to force the creation of the instance, otherwise if the service is created first it will be used again for the instances. 2001-09-19 17:56:15 +00:00
DataSource.pm
Database.pm Added better handling for error conditions in the Database code, and fixed the 'addRight' method to use it. 2001-07-26 00:54:37 +00:00
DatabaseHelper.pm
Input.pm * Added some comments (including some XXX comments where I realised we had missing code) 2001-06-03 10:11:58 +00:00
MagicCollectingArray.pm * Improved the helpfulness of the extremely verbose debugging information of PLIF.pm by quoting embedded variables 2001-06-04 06:13:22 +00:00
MagicPipingArray.pm Changed the magic piping array so that it is more consistent by removing the special casing of when there is only one return value. 2001-09-09 19:04:37 +00:00
MagicSelectingArray.pm * Improved the helpfulness of the extremely verbose debugging information of PLIF.pm by quoting embedded variables 2001-06-04 06:13:22 +00:00
Output.pm Added a bit more support for objects (as opposed to services): added a new objectCreate() constructor and an objectInit() method. 2001-05-13 18:04:52 +00:00
Program.pm * Added a section on common errors to Documentation.txt 2001-07-25 23:54:32 +00:00
README
Service.pm Fixing a gazillion syntax, logic and XML errors and adding some debug code. It compiles! 2001-06-03 14:49:41 +00:00

README

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.