cvsuser 02/11/01 11:59:20
Modified: App-Context/lib/App devguide.pod
Log:
removed references to P5EEx::Blue
Revision Changes Path
1.2 +71 -71 p5ee/App-Context/lib/App/devguide.pod
Index: devguide.pod
===================================================================
RCS file: /cvs/public/p5ee/App-Context/lib/App/devguide.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -w -r1.1 -r1.2
--- devguide.pod 9 Sep 2002 01:34:10 -0000 1.1
+++ devguide.pod 1 Nov 2002 19:59:19 -0000 1.2
@@ -6,26 +6,26 @@
=head1 NAME
-P5EEx::Blue::devguide - P5EE Developer's Guide
+App::devguide - App Developer's Guide
=head1 INTRODUCTION
This is the Developer's Guide to the
-P5EE (Perl 5 Enterprise Environment).
+App (Perl 5 Enterprise Environment).
You can find out more background to the project on the web.
http://www.officevision.com/pub/p5ee
http://p5ee.perl.org
-=head1 P5EE DESIGN PHILOSOPHY
+=head1 App DESIGN PHILOSOPHY
-When the P5EE project was begun, there were already
+When the App project was begun, there were already
* many outstanding Perl packages on CPAN
* an excellent systems architecture for Perl webapps (mod_perl)
* several excellent web application development frameworks
-So why was P5EE needed?
+So why was App needed?
For a variety of reasons, there was never sufficient unity of
purpose or direction within the Perl community to provide
@@ -51,20 +51,20 @@
term "Enterprise Systems" in Perl was actually focused on
"Web Systems" in Perl with a relational database.
-The goal of the P5EE design is to unify the Perl community
+The goal of the App design is to unify the Perl community
on a framework for cooperation, while providing flexibility in
the areas that might otherwise divide the community.
-Essentially, everything in P5EE is overridable and customizable,
+Essentially, everything in App is overridable and customizable,
but good defaults are provided for everything as well.
-On the practical side, P5EE was also designed to allow for gradual
+On the practical side, App was also designed to allow for gradual
adoption and incorporation into existing projects.
-=head1 P5EE Execution Flow: CGI
+=head1 App Execution Flow: CGI
The first step to understanding the flow of execution through
-the P5EE framework is to understand the flow in the CGI
+the App framework is to understand the flow in the CGI
Context.
This is one of the most challenging contexts
@@ -75,7 +75,7 @@
=head2 cgi-bin/p5x and the Initialization Config File
-All usage of P5EE from the web can be driven through the CGI program,
+All usage of App from the web can be driven through the CGI program,
"cgi-bin/p5x". (Actually, depending on the settings in the Initialization
Config File, the "p5x" program might not be a CGI program at all.)
The p5x program should be installed at a location which is executable
@@ -125,7 +125,7 @@
Some sample lines in the .conf file are:
- perlinc = /usr/ov/acoc/dev/src/P5EEx-Blue, /usr/ov/acoc/dev/lib/perl5/5.6.0
+ perlinc = /usr/ov/acoc/dev/src/Appx-Blue, /usr/ov/acoc/dev/lib/perl5/5.6.0
debugmode = record
showsession = 1
gzip = 1
@@ -135,22 +135,22 @@
perlinc - directories to search for perl modules
debugmode - (off|record|replay) useful for recording a failed CGI request and
replaying it for debugging
- debug -
(0|1,P5EEx::Blue::Context::CGI|6,P5EEx::Blue::Repository::DBI.select_rows)
+ debug - (0|1,App::Context::CGI|6,App::Repository::DBI.select_rows)
showsession - (0|1) show the contents of the session in an HTML comment
gzip - (0|1) allows compression of HTML output if the client browser
supports it
Additional variables may be provided. However, suitable defaults
are usually detected if they are not supplied.
- contextClass - (i.e. P5EEx::Blue::Context::CGI) class for the context
- configClass - (i.e. P5EEx::Blue::Config::File) class for the config
+ contextClass - (i.e. App::Context::CGI) class for the context
+ configClass - (i.e. App::Config::File) class for the config
configFile - (i.e. "config.pl") name of the main configuration file
- configSerializerClass - (i.e. P5EEx::Blue::Serializer::Dumper) class for config
deserialization
- sessionClass - (i.e. P5EEx::Blue::Session::HTMLHidden) class for the session
+ configSerializerClass - (i.e. App::Serializer::Dumper) class for config
deserialization
+ sessionClass - (i.e. App::Session::HTMLHidden) class for the session
defaultWname - widget name to be the first current_widget to be displayed
- scriptUrlDir - URL of P5EE script directory (i.e. "/cgi-bin")
+ scriptUrlDir - URL of App script directory (i.e. "/cgi-bin")
scriptDir - Directory corresponding to the scriptUrlDir
- htmlUrlDir - URL of P5EE docs directory
+ htmlUrlDir - URL of App docs directory
htmlDir - Directory corresponding to the htmlUrlDir
After the Initialization Config File is read into %main::conf, the
@@ -163,35 +163,35 @@
useful for debugging at the command line
(i.e. "p5x -debugmode=replay -debug=1 -gzip=0").
-=head2 use P5EEx::Blue::P5EE
+=head2 use App
-Next, the P5EEx::Blue::P5EE module is included, which does the following:
+Next, the App module is included, which does the following:
* disable "Use of uninitialized value" warnings
* use Exception::Class; # enable Exception inheritance
- * use P5EEx::Blue::Exceptions; # define P5EE exceptions
+ * use App::Exceptions; # define App exceptions
-The base class of all P5EE exceptions is "P5EEx::Blue::Exception".
-Derived from this base exception, each component service of P5EE
+The base class of all App exceptions is "App::Exception".
+Derived from this base exception, each component service of App
has its own base class as follows.
- P5EEx::Blue::Exception::Context
- P5EEx::Blue::Exception::Config
- P5EEx::Blue::Exception::Serializer
- P5EEx::Blue::Exception::Repository
- P5EEx::Blue::Exception::Security
- P5EEx::Blue::Exception::Session
- P5EEx::Blue::Exception::Widget
- P5EEx::Blue::Exception::TemplateEngine
- P5EEx::Blue::Exception::Procedure
- P5EEx::Blue::Exception::Messaging
- P5EEx::Blue::Exception::LogChannel
+ App::Exception::Context
+ App::Exception::Config
+ App::Exception::Serializer
+ App::Exception::Repository
+ App::Exception::Security
+ App::Exception::Session
+ App::Exception::Widget
+ App::Exception::TemplateEngine
+ App::Exception::Procedure
+ App::Exception::Messaging
+ App::Exception::LogChannel
=head2 cgi-bin/p5x and bootstrapping the environment
The "p5x" program then executes the following line.
- my $context = P5EEx::Blue::P5EE->context(\%main::conf);
+ my $context = App->context(\%main::conf);
This instantiates a $context object, passing the
global %main::conf hash as an argument.
@@ -200,50 +200,50 @@
CGI, the $context may survive to serve more than a single
request or to dispatch many events coming from the network
or from a user. In that case, the
-P5EEx::Blue::P5EE->context() method may return an
+App->context() method may return an
already-instantiated $context object. The $context
is a singleton per process.
-=head2 P5EEx::Blue::P5EE->context()
+=head2 App->context()
If the "contextClass" variable is in the argument hash, it is used.
Otherwise, if the "p5x" program is running in the CGI context
(HTTP_USER_AGENT environment variable is set) or at the
-command line, the P5EEx::Blue::Context::CGI class
+command line, the App::Context::CGI class
will be assumed.
The code for the selected class is loaded and a $context
of the appropriate class is instantiated.
-For the CGI context, the P5EEx::Blue::Context::CGI->new()
+For the CGI context, the App::Context::CGI->new()
method is called, and the arguments of the context() method
call (%main::conf, in this case) are passed on to it.
-=head2 P5EEx::Blue::Context::CGI->new()
+=head2 App::Context::CGI->new()
-The constructor (new()) for P5EEx::Blue::Context::CGI is actually provided
-by its parent class, P5EEx::Blue::Context.
+The constructor (new()) for App::Context::CGI is actually provided
+by its parent class, App::Context.
If the "configClass" was not specified in the arguments
-(%main::conf, in this case), P5EEx::Blue::Config::File is assumed.
+(%main::conf, in this case), App::Config::File is assumed.
It is instantiated, once again passing on the hash of initialization args,
and the result is stored in $self->{config};
-Then the P5EEx::Blue::Context::CGI->init() method is called to
+Then the App::Context::CGI->init() method is called to
complete the $context constructor. A CGI object is created
and added to the %args to be passed on to Session instantiation.
If the "sessionClass" was not specified in the arguments,
-P5EEx::Blue::Session::HTMLHidden is assumed.
+App::Session::HTMLHidden is assumed.
It is instantiated, once again passing on the hash of initialization args,
and the result is stored in $self->{session};
-=head2 P5EEx::Blue::Config::File->new()
+=head2 App::Config::File->new()
-The constructor (new()) for P5EEx::Blue::Config::File is actually provided
-by its grand-parent class, P5EEx::Blue::Reference.
-It creates a reference by calling P5EEx::Blue::Config::File->create(),
+The constructor (new()) for App::Config::File is actually provided
+by its grand-parent class, App::Reference.
+It creates a reference by calling App::Config::File->create(),
blesses it into the class, calls init()
-(P5EEx::Blue::Reference->init()) which does nothing,
+(App::Reference->init()) which does nothing,
and then returns the constructed Config::File object.
The Config::File->create() method loads data from a configuration
@@ -262,7 +262,7 @@
9. p5ee.perl 10. config.perl
11. p5ee.conf 12. config.conf
-By convention, "config.pl" is the config file for P5EE CGI scripts.
+By convention, "config.pl" is the config file for App CGI scripts.
However, the first file that is found is assumed to be the relevant config file.
If no config file is found or if it cannot be opened, an exception is thrown.
Otherwise, the text is read in from the file and deserialized into
@@ -273,12 +273,12 @@
is used to determine the Serializer class to use for deserialization.
pl # use "eval" instead of a serializer
- perl # P5EEx::Blue::Serializer::Dumper (like "pl" but use a serializer)
- xml # P5EEx::Blue::Serializer::XMLSimple
- ini # P5EEx::Blue::Serializer::Ini
- properties # P5EEx::Blue::Serializer::Properties
- conf # P5EEx::Blue::Serializer::Properties
- stor # P5EEx::Blue::Serializer::Storable
+ perl # App::Serializer::Dumper (like "pl" but use a serializer)
+ xml # App::Serializer::XMLSimple
+ ini # App::Serializer::Ini
+ properties # App::Serializer::Properties
+ conf # App::Serializer::Properties
+ stor # App::Serializer::Storable
If the file is a .pl file, no serializer is implied. It is just eval'ed.
(It must have "$var =" as the first non-whitespace text in the file,
@@ -289,7 +289,7 @@
The resulting hash reference is returned and stored in $context->{config}.
-=head2 P5EEx::Blue::Context::CGI->init()
+=head2 App::Context::CGI->init()
The init() method is where the CGI object is created, parsing the
environment variables and STDIN which are
@@ -305,21 +305,21 @@
Another sort of debugging is initialized if the "debug"
variable is supplied in the %args. This turns on a global debug
-flag ($P5EEx::Blue::DEBUG) and sets the debug scope
+flag ($App::DEBUG) and sets the debug scope
(which classes or methods should produce debug output).
To support migration of code, the CGI object can also be passed into
-the P5EE->context() method as an argument, and it will be used rather
+the App->context() method as an argument, and it will be used rather
than trying to create a new one. However, this is not the execution
path being described here.
-=head2 P5EEx::Blue::Session::HTMLHidden->new()
+=head2 App::Session::HTMLHidden->new()
-The constructor (new()) for P5EEx::Blue::Session::HTMLHidden is actually provided
-by its grand-parent class, P5EEx::Blue::Reference.
-It creates a hash reference by calling P5EEx::Blue::Reference->create(),
+The constructor (new()) for App::Session::HTMLHidden is actually provided
+by its grand-parent class, App::Reference.
+It creates a hash reference by calling App::Reference->create(),
blesses it into the class, calls init()
-(P5EEx::Blue::Session::HTMLHidden->init()),
+(App::Session::HTMLHidden->init()),
and then returns the constructed Session::HTMLHidden object.
The init() method looks at the CGI variables in the request
@@ -349,7 +349,7 @@
everything at the outset and shut it all down at the completion
of each request.
-=head2 P5EEx::Blue::Context::CGI->dispatch_events()
+=head2 App::Context::CGI->dispatch_events()
The CGI variables are examined. Variables which start with "p5ee.event"
are identified as events to be handled, and they are saved for later.
@@ -400,10 +400,10 @@
$self->shutdown() which gracefully shuts down all connections
to repositories.
-=head2 P5EEx::Blue::Context::CGI->display_current_widget()
+=head2 App::Context::CGI->display_current_widget()
The display_current_widget() method is implemented in the parent
-class, P5EEx::Blue::Context::HTML.
+class, App::Context::HTML.
A attribute "session.current_widget" contains the name of the current
widget to display.
@@ -421,7 +421,7 @@
Then the current widget is summoned and handed to the display_items()
method.
-=head2 P5EEx::Blue::Context::CGI->display_items()
+=head2 App::Context::CGI->display_items()
The job of display items is to take the list of args, convert them
to HTML, and print them to STDOUT with the appropriate HTTP headers
@@ -451,7 +451,7 @@
That's it. All of the processing for a single CGI request is complete.
All application code is wrapped up in user interface widgets
-(P5EEx::Blue::Widget::HTML) and entity widgets (P5EEx::Blue::Widget::Entity).
+(App::Widget::HTML) and entity widgets (App::Widget::Entity).
The user interface widgets are mostly prepackaged, but are configured
through the configuration file, allowing for a data-driven programming
style on the user interface. The entity widgets store most of their state
