App-Context
view release on metacpan or search on metacpan
=cut
#############################################################################
# DISTRIBUTION
#############################################################################
=head1 Distribution: App-Context
The App-Context distribution is the core set of modules implementing
the core of an enterprise application development framework.
http://www.officevision.com/pub/App-Context
* Version: 0.01
It provides the following services.
* Application Configuration (App::Conf::*)
* Session Management (App::Session::*)
* Remote Procedure Call (App::Procedure::*)
The requirements which have been satisfied
(or features implemented) have an "x" by them, whereas the requirements
which have yet-to-be satisfied have an "o" by them.
o an Enterprise Software Architecture, supporting all the Attributes
http://www.officevision.com/pub/p5ee/definitions.html
o a Software Architecture supporting many Platforms
http://www.officevision.com/pub/p5ee/platform.html
o a pluggable interface/implementation service architecture
o support developers who wish to use portions of the App-Context
framework without giving up their other styles of programming
(and support gradual migration)
=head2 Distribution Design
The distribution is designed in such a way that most of the functionality
is actually provided by modules outside the App namespace.
The goal of the App-Context framework
is to bring together many technologies to make a
unified whole. In essence, it is collecting and unifying the good work
of a multitude of excellent projects which have already been developed.
This results in a Pluggable Service design which allows just about
everything in App-Context to be customized. These Class Groups are described
in detail below.
Where a variety of excellent, overlapping or redundant, low-level modules
exist on CPAN (i.e. L<date and time modules|App::datetime>),
a document is
written to explain the pros and cons of each.
Where uniquely excellent modules exist on CPAN, they are named outright
as the standard for the App-Context framework.
They are identified as dependencies
in the App-Context CPAN Bundle file.
=head2 Class Groups
The major Class Groups in the App-Context distribution fall into three categories:
Core, Core Services, and Services.
=over
#############################################################################
=head2 info()
* Signature: $ident = App->info();
* Param: void
* Return: $ident string
* Throws: App::Exception
* Since: 0.01
Gets version info about the framework.
=cut
sub info {
&App::sub_entry if ($App::trace);
my $self = shift;
my $retval = "App-Context ($App::VERSION)";
&App::sub_exit($retval) if ($App::trace);
return($retval);
}
lib/App/Context.pm view on Meta::CPAN
use Carp qw(confess shortmess);
use Date::Format;
use Time::HiRes;
use IO::Handle; # for the STDOUT->autoflush() method
use IO::Socket;
use IO::Socket::INET;
=head1 NAME
App::Context - An application framework for web applications, command-line programs, server programs, and web services
=head1 SYNOPSIS
# ... official way to get a Context object ...
use App;
$context = App->context();
$context->dispatch_events(); # dispatch events
$conf = $context->conf(); # get the configuration
# any of the following named parameters may be specified
lib/App/Context.pm view on Meta::CPAN
#print STDERR "ERROR: Context->get($var): eval ($perl): $@\n" if ($@);
$self->dbgprint("Context->so_get($name,$var) (indexed) = [$value]")
if ($App::DEBUG && $self->dbg(3));
}
&App::sub_exit($value) if ($App::trace);
return $value;
}
# This is a very low-level _so_get() suitable for use within the App-Context
# framework. It requires you to separate $name and $var yourself.
sub _so_get {
&App::sub_entry if ($App::trace);
my ($self, $name, $var, $default) = @_;
my $value = $self->{session}{cache}{SessionObject}{$name}{$var};
if (! defined $value) {
$value = $self->{session}{store}{SessionObject}{$name}{$var};
if (! defined $value) {
$value = $self->{conf}{SessionObject}{$name}{$var};
lib/App/Context.pm view on Meta::CPAN
* Throws: App::Exception
* Since: 0.01
Sample Usage:
$context->dispatch_events();
The dispatch_events() method is called by the bootstrap environmental code
in order to get the Context object rolling. It causes the program to block
(wait on I/O), loop, or poll, in order to find events from the environment
and dispatch them to the appropriate places within the App-Context framework.
It is considered "protected" because no classes should be calling it.
=cut
sub dispatch_events {
&App::sub_entry if ($App::trace);
my ($self, $max_events_occurred) = @_;
$self->dispatch_events_begin();
lib/App/Session/Cookie.pm view on Meta::CPAN
This Session::Cookie maintains its state across
HTML requests by being embedded in an HTTP cookie.
As a result, it requires no server-side storage, so the sessions
never need to time out.
The Session::Cookie has an advantage over Session::HTMLHidden in that
data does not need to be posted to a URL for the session data to be
transmitted to it. This allows that the state can be propagated
properly to sub-components of an HTML page such as
* frame documents within a frameset (<frame src=...>)
* dynamically generated images (<img src=...>, <input type=image src=...>)
Limits on cookie storage are as follows, according to "Dynamic HTML,
The Definitive Reference" by O'Reilly in the DOM Reference under
"document.cookie".
* max 2000 chars per cookie (recommended, although 4000 supposedly allowed)
* max 20 cookies per domain
This allows for roughly 40K of session storage.
lib/App/datetime.pod view on Meta::CPAN
http://search.cpan.org/~drolsky/DateTime/
http://search.cpan.org/~drolsky/DateTime/lib/DateTime.pm
The latest significant entrant (and quite promising) in the perl
date/time area is Datetime.pm. It attempts to be the definitive
date/time module for perl, building on the work of Time::Piece
and Class::Date.
Furthermore, the DateTime module is not alone. Rather, it is
part of a project where many date/time developers collaborate
for an entire framework of date/time modules.
* OO interface
* Parsing of dates provided by DateTime::Format::* modules
* Flexible formatting using POSIX strftime() format specifiers.
(formatting done automatically during object stringification)
* Limited internationalization support.
* Good date math support.
* Unknown support for dates outside [1970-2038]
* Moderate support on Win32 platform.
lib/App/devguide.pod view on Meta::CPAN
http://www.officevision.com/pub/p5ee
http://p5ee.perl.org
=head1 App DESIGN PHILOSOPHY
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 App needed?
For a variety of reasons, there was never sufficient unity of
purpose or direction within the Perl community to provide
a coherent blueprint of what Enterprise Programming in Perl is
or how to do it.
* What are the pieces?
* What pieces are default? standard? mandatory? optional?
* How do they fit together?
* How can I override or customize them?
* What techniques do I need to use to assemble them effectively?
After "Enterprise Systems" were defined (see website), the field
of existing frameworks, solutions, and components was surveyed.
The goal was to examine everything that people were already doing,
divide it into pieces that seemed interchangeable, and come up
with a unified blueprint. Pieces that people often like to do
differently (template systems, persistence frameworks, configuration
files) were allowed to vary, while their essential contribution
to the working system was standardized in the framework.
It should be noted that most of the work on what people might
term "Enterprise Systems" in Perl was actually focused on
"Web Systems" in Perl with a relational database.
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 App is overridable and customizable,
but good defaults are provided for everything as well.
On the practical side, App was also designed to allow for gradual
adoption and incorporation into existing projects.
=head1 App Execution Flow: CGI
The first step to understanding the flow of execution through
the App framework is to understand the flow in the CGI
Context.
This is one of the most challenging contexts
to develop for because of the stateless nature of HTTP,
the need to initialize all resources before accessing them,
and the need to properly shut down all resources after using
them or in case of user abort.
=head2 cgi-bin/app and the Initialization Config File
lib/App/exceptions.pod view on Meta::CPAN
Programming with Exceptions
is a much more reliable way to prepare for unusual conditions
than trying to handle error codes returned from functions and methods
That is why programming with exceptions is an Enterprise Programming
topic. However, Perl has not always supported programming with
exceptions, and many Perl programmers are not familiar with this
style of programming using Perl.
This document was written to explain the support within the Perl
language for programming using exceptions in general. It also explains
the standards for exception programming in the App-Context framework.
The short answer is that we recommend the following modules
to assist in exception programming.
Carp
CGI::Carp
Fatal
Exception::Class
Devel::Stacktrace
lib/App/faq.pod view on Meta::CPAN
podchecker(\*DATA);
__END__
=head1 NAME
App::faq - App-Context Frequently Asked Questions
=head1 INTRODUCTION
This is the FAQ for the
App-Context software framework
(a variant of the 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 GENERAL
=head2 Why should I use App-Context rather than J2EE or .NET?
lib/App/faq.pod view on Meta::CPAN
If you have a desire to program in Java and you like the API's
that Sun (and others) have created, you should probably focus
on Java. I think that things could be a lot simpler (or maybe
higher level) than the J2EE specifies them.
It seemed that the one thing that Perl was lacking was
a blueprint for large-scale development and deployment of
high-performance, high-availability systems (i.e. enterprise
systems) along with guides of discipline for coding and
documentation. The App-Context framework fills this gap.
So that's the explanation of "why App-Context?"
For an explanation of "why not App-Context?" you might consider that it
is still largely vaporware.
=head2 How well does the App-Context fit into a .NET technical strategy?
It may seem that App-Context is most at home with the following technologies.
* Perl, Linux, Apache, CGI, and MySQL.
However, the App-Context framework abstracts much of the
runtime environment, so that it is just as easy to use:
* Perl, Windows NT, IIS, ISAPI, and SQLServer.
So the question becomes, "How well does Perl fit into a .NET
technical strategy?"
Although Perl is not a core .NET language from Microsoft's
perspective, the following three considerations would suggest
that Perl is not outside of a .NET technical strategy.
lib/App/faq.pod view on Meta::CPAN
Enterprise Perl are SOAP projects, XML projects, DBD/DBI::*,
Templating projects, etc. These are all making dramatic contributions,
and they need not change anything they are doing in order to continue
to do so.
On the contrary, the responsibility is on the designers of the App-Context
to accommodate and incorporate these many enterprise-class technologies
into an integrates whole. Browse the classes envisioned for App-Context
to see one way that these might fit together. Take
special note of the "Classes (Planned)" at the bottom of the
"All Classes" frame.
http://www.officevision.com/pub/p5ee/software/htdocs/api/
As for mod_perl, it would seem to be the container of choice for
web applications and SOAP services.
http://www.officevision.com/pub/p5ee/software/htdocs/Appx/Blue/Context.html
There is no need for the mod_perl project to explicitly
integrate with App-Context. However, in the spirit of community,
lib/App/installguide.pod view on Meta::CPAN
work in separate directories.)
/usr/mycompany/spadkins
/usr/mycompany/joe
/usr/mycompany/marysue
/usr/mycompany/devel
/usr/mycompany/qagroup
These are independent development "sandboxes".
Later, when we start making releases of the software (which includes the App
framework), we will create other environment directories like this.
/usr/mycompany/0.5.0
/usr/mycompany/0.5.1
/usr/mycompany/1.0.0
/usr/mycompany/2.17.10
All of these directories will have their own self-contained installation
of software. Named versions (i.e. "test", "qa", "prod") are simply
symbolic links to the particular version to which they currently apply.
lib/App/installguide.pod.ota view on Meta::CPAN
work in separate directories.)
/usr/mycompany/spadkins
/usr/mycompany/joe
/usr/mycompany/marysue
/usr/mycompany/devel
/usr/mycompany/qagroup
These are independent development "sandboxes".
Later, when we start making releases of the software (which includes the App
framework), we will create other environment directories like this.
/usr/mycompany/0.5.0
/usr/mycompany/0.5.1
/usr/mycompany/1.0.0
/usr/mycompany/2.17.10
All of these directories will have their own self-contained installation
of software. Named versions (i.e. "test", "qa", "prod") are simply
symbolic links to the particular version to which they currently apply.
lib/App/installguide/hosted.pod view on Meta::CPAN
=head1 NAME
App::installguide::hosted - Instructions on installing the App::Context framework in a web-hosting (non-root) environment
=head1 DESCRIPTION
These are instructions on installing the App::Context framework in a web-hosting (non-root) environment.
=head1 ASSUMPTIONS
* You get command line access but not root.
* You have access to a MySQL database engine (and permissions to create at least 3 databases)
=head1 SET UP THE CPAN SHELL
Installing software from CPAN into a non-system area requires a little setup.
lib/App/installguide/hosted.pod view on Meta::CPAN
./Build test
./Build install
Sometimes a distribution fails some of the tests. If it does, the CPAN shell
will not install it. When you build it manually (as shown above), you may
decide that it is an error in the test suite rather than an error in the
modules themselves. In this case, you can continue with the "install" step.
Then reenter the CPAN shell and install the next module.
IMPORTANT: If anyone discovers problems with these instructions or the
distributions related to the App::Context framework, please report them to me:
spadkins@gmail.com
[I want to make this framework dirt simple to set up and use. -- spa]
=head1 SETTING UP A MySQL DATABASE
This will vary depending on your web hosting provider (and presumes they support
the use of MySQL databases). I went to a control panel and did all the setup.
(This is all just an example of how I did it so that I can refer to this in later
setup documentation. You will probably do this differently.)
I created three databases: "devel", "test", and "prod". The control panel
prepended my hosting username, so they ended up being called "username_devel",
lib/App/installguide/hosted.pod view on Meta::CPAN
mysql> select * from foo;
mysql> delete from foo where foo_dt = '2006-10-08';
mysql> select * from foo;
mysql> exit
=head1 SET UP THE FRAMEWORK TO READ THE DATABASE
=head2 CREATE app.conf
There are two kinds of configuration files in an application
written for the App::Context framework: app.conf and app.pl.
The "app.conf" file is the low-level configuration file.
"app.conf" is sometimes called the "options file" because
it is read by App::Options.
It contains parameters which are specific to the deployment
rather than to the structure of the application.
It can be thought of as a "deployment descriptor".
For our purposes, the only thing unique about our installation
is the database connection information.
lib/App/installguide/hosted.pod view on Meta::CPAN
dbname = username_prod
dbuser = username_dbuser
dbpass = my_password_here
chmod 600 $PREFIX/etc/app/app.conf
=head2 CREATE app.pl
The "app.pl" file is the Application Configuration file.
This is where you define (and assemble) Services (i.e. components)
in the App::Context framework.
When an application is developed, a file like "app.pl" is part of the source
code of that application. This file is not usually modified at the time
it is deployed along with supporting code into production.
For our example, we configure the Repository named
"dbprod" as a service in the "App::Repository::MySQL" class.
Then we configure the "default" Repository as an alias for "dbprod".
vi $PREFIX/etc/app/app.pl
lib/App/installguide/hosted.pod view on Meta::CPAN
# app Repository default get_rows foo
$data = [
[
'2',
'2006-09-28',
'yowza',
'5'
]
];
All programs that are built using the framework (with App-Options, App-Context,
and App-Repository) (such as "app") get a number of built-in features for free.
You can experiment with the following.
app --help
app --debug_options=3
app --debug_conf
app --debug_sql Repository default get_rows foo
app --trace Repository default get_rows foo
=head1 YOUR FIRST WEB APPLICATION
lib/App/perlstyle.pod view on Meta::CPAN
## $Id: perlstyle.pod,v 1.2 2002/11/01 20:18:22 spadkins Exp $
#############################################################################
=head1 NAME
App::perlstyle - App::Context Perl Style Guide
=head1 INTRODUCTION
The following document describes some of the coding standards used in
writing the App::Context framework (App-Options, App-Context, App-Repository,
App-Widget, and other minor distributions). This document exists for two
purposes:
=over
=item 1. To provide a guideline for people who wish to contribute to or
extend code in the App::Context framework.
=item 2. To provide a samples style guide to any development group who
desires a simple, effective coding standard for programming in Perl.
=back
Note that these are all guidelines, not unbreakable rules.
Note that with much of this document, it is not so much the Right Way as
it is One Reasonable Way. Everyone needs to have conventions in order to
lib/App/perlstyle.pod view on Meta::CPAN
Revision 1.2 2002/11/01 20:18:22 spadkins
convert from P5EEx::Blue to App::Context
Revision 1.1 2002/09/09 01:34:10 spadkins
first import
Revision 1.2 2001/11/30 16:00:52 spadkins
Renamed 'Component' to 'Service' throughout. Improved perldocs.
Revision 1.1 2001/11/22 05:16:59 spadkins
Major new architectural framework proposal
Revision 1.1 2001/11/16 23:21:38 spadkins
initial stuff
=head1 VERSION
$Id: perlstyle.pod,v 1.2 2002/11/01 20:18:22 spadkins Exp $
lib/App/quickstart.pod view on Meta::CPAN
This is the Developer's Quickstart Guide to the App::Context Framework.
Its focus is to give a minimum amount of theoretical or explanatory
background and get right into learning by example.
=head1 DOCUMENTATION OVERVIEW
That having been said, it is also important to let you know
what documentation exists and what state it is in.
I got started building the App::Context framework a while ago.
The documentation is very limited. This is an effort to bring it all together.
This list shows how all of the documentation fits together and in what state
it is.
=head2 PURE DOCUMENTATION
The following documentation is in good shape.
To get started, read them more or less in the order shown.
=over
lib/App/quickstart.pod view on Meta::CPAN
=item * +-- L<App::Context::HTTP> - A program running in a CGI/mod_perl context.
=item * +-- L<App::Context::Server> - A program running in a multi-process server context.
=item * =====+-- L<App::Context::ClusterController> - Running in a multi-node cluster context.
=item * =====+-- L<App::Context::ClusterNode> - Running on a single node of a cluster.
=item * +-- L<App::Context::NetServer> - Another flavor of server context (not yet implemented).
=item * L<App::Exceptions> - Defines the exceptions used in the framework.
=item * L<App::UserAgent>
=item * L<App::Request>
=item * +-- L<App::Request::CGI>
=item * L<App::Response>
=item * L<App::Session>
lib/App/quickstart.pod view on Meta::CPAN
use App::Repository;
{
my $context = $App->context();
my $db = $context->repository();
# perform database ops like ...
# my $rows = $db->get_rows("customer", { last_name => "Smith" }, ["first_name", "last_name", "birth_dt"]);
# my $hashes = $db->get_hashes("customer", { "birth_dt.le" => "2000-01-01" }, ["first_name", "last_name", "birth_dt"]);
# my $age = $db->get("customer", { customer_id => 45 }, "age");
}
The best parts about writing database programs with App::Repository in the App::Context framework
is that all of your programs get automatic SQL debugging, timing, and explaining.
prog --debug_sql # show all SQL statements and their timings
prog --debug_sql=2 # show all SQL statements and their timings and all rows returned from selects
prog --debug_sql --explain_sql # show SQL statements and explain them
See L<App::Options>, L<App::Repository::quickstart>, and L<App::Repository::devguide> for more info on this.
=head1 QUICK START TO OBJECT-ORIENTED COMMAND LINE PROGRAMS
( run in 1.001 second using v1.01-cache-2.11-cpan-e1769b4cff6 )