App-Context
view release on metacpan or search on metacpan
#############################################################################
## $Id: App.pm 13887 2010-04-06 13:36:42Z spadkins $
#############################################################################
package App;
$VERSION = (q$Revision: 13887 $ =~ /(\d[\d\.]*)/)[0]; # VERSION numbers generated by svn
use strict;
# eliminate warnings about uninitialized values
$SIG{__WARN__} = sub { warn @_ unless $_[0] =~ /Use of uninitialized value/};
use Exception::Class; # enable Exception inheritance
use App::Exceptions;
use IO::Handle;
=head1 NAME
App - Backplane for core App services
=head1 SYNOPSIS
use App;
my ($context, $conf, $object);
$context = App->context(); # singleton per process
$conf = App->conf(); # returns a hashref to conf
$context = App->new();
$object = App->new($class);
$object = App->new($class, $method);
$object = App->new($class, $method, @args);
=head1 DOCUMENT STATUS
This documentation is out of date and needs review and revision.
Please start with the L<App::quickstart> document.
=head1 DESCRIPTION
The App module is the module from which core services are called.
=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::*)
* Session Objects and Remote Method Invocation (App::SessionObject::*)
* Multiprocess-safe Name-Value Storage (App::SharedDatastore::*)
* Shared Resource Pooling and Locking (App::SharedResourceSet::*)
One of App-Context's extended services (App::Repository::*)
adds distributed transaction capabilities and access to data
from a variety of sources through a uniform interface.
In the same distribution (App-Repository), is a base class,
App::RepositoryObject, which serves as the base class for
implementing persistent business objects.
http://www.officevision.com/pub/App-Repository
Another of App-Context's extended services (App::Widget::*)
adds simple and complex active user interface widgets.
These widgets can be used to supplement an existing application's
user interface technology (template systems, hard-coded HTML, etc.)
or the Widget system can be used as the central user interface paradigm.
http://www.officevision.com/pub/App-Widget
App-Context and its extended service distributions were
inspired by work on the Perl 5 Enterprise Environment project,
and its goal is to satisfy the all of the requirements embodied in
the Attributes of an Enterprise System.
See the following web pages for more information about the P5EE project.
http://p5ee.perl.org/
http://www.officevision.com/pub/p5ee/
=head2 Distribution Requirements
The following are enumerated requirements for the App-Context distribution.
It forms a high-level feature list.
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
=item * Class Group: L<C<Core>|"Class Group: Core">
=item * Class Group: L<C<Context>|App::Context>
- encapsulates the runtime environment and the event loop
=item * Class Group: L<C<Conf>|App::Conf>
- retrieve and access configuration information
=item * Class Group: L<C<Session>|App::Session>
- represents the state associated with a sequence of multiple events
=item * Class Group: L<C<Serializer>|App::Serializer>
- transforms a perl struct to a scalar and back
=item * Class Group: L<C<Procedure>|App::Procedure>
- a (potentially remote) procedure which may be executed
=item * Class Group: L<C<Messaging>|App::Messaging>
- a message queue with configurable quality of service
=item * Class Group: L<C<Security>|App::Security>
- provides authentication and authorization
=item * Class Group: L<C<LogChannel>|App::LogChannel>
- a logging channel through which messages may be logged
=item * Class Group: L<C<SharedDatastore>|App::SharedDatastore>
- a data storage area which is shared between processes
=item * Class Group: L<C<SharedResourceSet>|App::SharedResourceSet>
- a set of shared resources which may be locked for exclusive access
=back
=cut
#############################################################################
# CLASS GROUP
#############################################################################
=head1 Class Group: Core
The Core Class Group contains the following classes.
=over
=item * Class: L<C<App>|"Class: App">
=item * Class: L<C<App::Reference>|App::Exceptions>
}
&App::sub_exit($context{$name}) if ($App::trace);
return($context{$name});
}
sub shutdown {
&App::sub_entry if ($App::trace);
my ($self, $name) = @_;
$name = "default" if (!defined $name);
$context{$name}->shutdown() if (defined $context{$name});
delete $context{$name};
&App::sub_exit() if ($App::trace);
}
#############################################################################
# conf()
#############################################################################
=head2 conf()
* Signature: $conf = App->conf(%named);
* Param: conf_class class [in]
* Param: config_file string [in]
* Return: $conf App::Conf
* Throws: App::Exception::Conf
* Since: 0.01
This gets the Conf object from the Context.
If args are passed in, they are only effective in affecting the Context
if the Context has not been instantiated before.
After the Context is instantiated by either the App->context() call or the
App->conf() call, then subsequent calls to either method may or may not
include arguments. It will not have any further effect because the
Context object instantiated earlier will be used.
=cut
sub conf {
&App::sub_entry if ($App::trace);
my $self = shift;
my $retval = $self->context(@_)->conf();
&App::sub_exit($retval) if ($App::trace);
$retval;
}
#############################################################################
# info()
#############################################################################
=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);
}
#############################################################################
# Aspect-oriented programming support
#############################################################################
# NOTE: This can be done much more elegantly at the Perl language level,
# but it requires version-specific code. I created these subroutines so that
# any method that is instrumented with them will enable aspect-oriented
# programming in Perl versions from 5.5.3 to the present.
#############################################################################
my $calldepth = 0;
#############################################################################
# sub_entry()
#############################################################################
=head2 sub_entry()
* Signature: &App::sub_entry;
* Signature: &App::sub_entry(@args);
* Param: @args any
* Return: void
* Throws: none
* Since: 0.01
This is called at the beginning of a subroutine or method (even before $self
may be shifted off).
=cut
sub sub_entry {
if ($App::trace) {
my ($stacklevel, $calling_package, $file, $line, $subroutine, $hasargs, $wantarray, $text);
$stacklevel = 1;
($calling_package, $file, $line, $subroutine, $hasargs, $wantarray) = caller($stacklevel);
while (defined $subroutine && $subroutine eq "(eval)") {
$stacklevel++;
($calling_package, $file, $line, $subroutine, $hasargs, $wantarray) = caller($stacklevel);
}
my ($name, $obj, $class, $package, $sub, $method, $firstarg, $trailer);
# split subroutine into its "package" and the "sub" within the package
if ($subroutine =~ /^(.*)::([^:]+)$/) {
$package = $1;
$sub = $2;
}
# check if it might be a method call rather than a normal subroutine call
if ($#_ >= 0) {
$class = ref($_[0]);
( run in 0.586 second using v1.01-cache-2.11-cpan-e1769b4cff6 )