App - Backplane for core App services
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);
The App module is the module from which core services are called.
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/
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)
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. date and time modules), 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.
The major Class Groups in the App-Context distribution fall into three categories: Core, Core Services, and Services.
Class Group: Core
Core
Class Group: Context - encapsulates the runtime environment and the event loop
Context
Class Group: Conf - retrieve and access configuration information
Conf
Class Group: Session - represents the state associated with a sequence of multiple events
Session
Class Group: Serializer - transforms a perl struct to a scalar and back
Serializer
Class Group: Procedure - a (potentially remote) procedure which may be executed
Procedure
Class Group: Messaging - a message queue with configurable quality of service
Messaging
Class Group: Security - provides authentication and authorization
Security
Class Group: LogChannel - a logging channel through which messages may be logged
LogChannel
Class Group: SharedDatastore - a data storage area which is shared between processes
SharedDatastore
Class Group: SharedResourceSet - a set of shared resources which may be locked for exclusive access
SharedResourceSet
The Core Class Group contains the following classes.
Class: App
App
Class: App::Reference
App::Reference
Class: App::Service
App::Service
Document: Perlstyle, Perl Style Guide
Perlstyle, Perl Style Guide
Document: Podstyle, POD Documentation Guide
Podstyle, POD Documentation Guide
Document: Datetime, Dates and Times in App-Context
Datetime, Dates and Times in App-Context
App is the main class through which all of the features of the Perl 5 Enterprise Environment may be accessed.
* Throws: Exception::Class::Base * Throws: App::Exception * Throws: App::Exception::Conf * Throws: App::Exception::Context * Since: 0.01
The class is entirely made up of static (class) methods. There are no constructors for objects of this class itself. Rather, all of the constructors in this package are really factory-style constructors that return objects of different classes. In particular, the new() method is really a synonym for context(), which returns a Context object.
This class supports the following capabilities.
Capability: Service Factory
This package allows you to construct objects (services) that you do not know the classes for at development time. These classes are specified through the configuration and are produced using this package as a class factory.
* Global Variable: %App::scope scope for debug or tracing output * Global Variable: %App::trace trace level * Global Variable: $App::DEBUG debug level * Global Variable: $App::DEBUG_FILE file for debug output
* Signature: App->use($class); * Param: $class string [in] * Return: void * Throws: <none> * Since: 0.01 Sample Usage: App->use("App::Widget::Entity");
The use() method loads additional perl code and enables aspect-oriented programming (AOP) features if they are appropriate. If these did not need to be turned on or off, it would be easier to simply use the following.
eval "use $class;"
The first AOP feature planned is the printing of arguments on entry to a method and the printing of arguments and return values on exit of a a method.
This is useful for debugging and the generation of object-message traces to validate or document the flow of messages through the system.
Detailed Conditions:
* use(001) class does not exist: throw a App::Exception * use(002) class never used before: should succeed * use(003) class used before: should succeed * use(004) can use class after: should succeed
* Signature: App->printargs($depth, $skipatend, @args); * Param: $depth integer [in] * Param: $skipatend integer [in] * Param: @args any [in] * Return: void * Throws: none * Since: 0.01
The App->new() method is not a constructor for an App class. Rather, it is a Factory-style constructor, returning an object of the class given as the first parameter.
If no parameters are given, it is simply a synonym for "App->context()".
* Signature: $context = App->new() * Signature: $object = App->new($class) * Signature: $object = App->new($class,$method) * Signature: $object = App->new($class,$method,@args) * Param: $class class [in] * Param: $method string [in] * Return: $context App::Context * Return: $object ref * Throws: Exception::Class::Base * Since: 0.01 Sample Usage: $context = App->new(); $dbh = App->new("DBI", "new", "dbi:mysql:db", "dbuser", "xyzzy"); $cgi = App->new("CGI", "new");
* Signature: $context = App->context(); # most common, used in "app" * Signature: $context = App->context(%named); # also used * Signature: $context = App->context($named, %named); # variation * Signature: $context = App->context($name, %named); # rare * Signature: $context = App->context($named, $name, %named); # rare * Param: context_class class [in] * Param: config_file string [in] * Param: prefix string [in] * Return: $context App::Context * Throws: App::Exception::Context * Since: 0.01 Sample Usage: $context = App->context(); $context = App->context( context_class => "App::Context::HTTP", config_file => "app.xml", );
This static (class) method returns the $context object of the context in which you are running. It tries to use some intelligence in determining which context is the right one to instantiate, although you can override it explicitly.
It implements a "Factory" design pattern. Instead of using the constructor of a class itself to get an instance of that class, the context() method of App is used. The former technique would require us to know at development time which class was to be instantiated. Using the factory style constructor, the developer need not ever know what physical class is implementing the "Context" interface. Rather, it is configured at deployment-time, and the proper physical class is instantiated at run-time.
The new() method of the configured Context class is called to instantiate the proper Context object. The $named args are combined with the %named args and passed as a single hash reference to the new() method.
Environment variables:
PREFIX - set the $conf->{prefix} variable if not set to set app root dir APP_CONTEXT_CLASS - set the Perl module to instantiate for the Context GATEWAY_INTERFACE - assume mod_perl, use App::Context::ModPerl HTTP_USER_AGENT - assume CGI, use App::Context::HTTP (otherwise, use App::Context::Cmd, assuming it is from command line)
* 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.
* Signature: $ident = App->info(); * Param: void * Return: $ident string * Throws: App::Exception * Since: 0.01
Gets version info about the framework.
* 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).
* Signature: &App::sub_exit(@return); * Param: @return any * Return: void * Throws: none * Since: 0.01
This subroutine is called just before you return from a subroutine or method.
* Author: Stephen Adkins <stephen.adkins@officevision.com> * License: This is free software. It is licensed under the same terms as Perl itself.
To install App::Context, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Context
CPAN shell
perl -MCPAN -e shell install App::Context
For more information on module installation, please visit the detailed CPAN module installation guide.