NAME

XAO::Objects - dynamic objects loader

SYNOPSIS

use XAO::Objects;

sub foo {
   ...
   my $page=XAO::Objects->new(objname => 'Web::Page');
}

DESCRIPTION

Loader for XAO dynamic objects. This module is most extensively used throughout all XAO utilities and packages.

The idea of XAO dynamic objects is to seamlessly allow multiple projects co-exist in the same run-time environment -- for instance multiple web sites in mod_perl environment. Using traditional Perl modules or objects it is impossible to have different implementations of an object in the same namespace -- once one site loads a Some::Object the code is then re-used by all sites executing in the same instance of Apache/mod_perl.

The architecture of XAO::Web and XAO::FS requires the ability to load an object by name and at the same time provide a pissibly different functionality for different sites.

This is achieved by always loading XAO objects using functions of XAO::Objects package.

Have a look at this example:

my $dobj=XAO::Objects->new(objname => 'Web::Date');

What happens when this code is executed is that in case current site has an extended version of Web::Date object -- this extended version will be returned, otherwise the standard Web::Date is used. This allows for customizations of a standard object specific to a web site without affecting other web sites.

For creating an site specific object based on standard object the following syntax should be used:

package XAO::DO::Web::MyObject;
use strict;
use XAO::Objects;

use base XAO::Objects->load(objname => 'Web::Page');

sub display ($%) {
    my $self=shift;
    my $args=get_args(\@_);

    .....
}

To extend or alter the functionality of a standard object the following syntax should be used to avoid infinite loop in the object loader:

package XAO::DO::Web::Date;
use strict;
use XAO::Objects;

use base XAO::Objects->load(objname => 'Web::Date', baseobj => 1);

XAO::Objects is not limited to web site use only, in fact it is used in XAO Foundation server to load database objects, in XAO::Catalogs to load custom catalog filters and so on.

FUNCTIONS

The following functions are available. They can be called either as 'XAO::Objects->function()' or as 'XAO::Objects::function()'. XAO::Objects never creates objects of its own namespace, so these are functions, not methods.

load

Pre-loads an object into memory for quicker access and inheritance.

On success returns class name of the loaded object, on error -- undefined value.

It is allowed to call load outside of any site context - it just would not check site specific objects.

Arguments:

objname  => object name (required)
baseobj  => ignore site specific objects even if they exist (optional)
sitename => should only be used to load Config object

When called from an established site context that context is checked for an optional configuration value /xao/objects/include that may contain a list of "library" projects that are checked for object implementations.

Alternatively, the list of library sites can be given in 'include' argument to load(). This is useful in loading prototypes of Config itself when the configuration is not available yet.

Given an objname equal "Foo::Bar" the logic is this:

1. If there a current site, or a sitename is given, check that site
   for objects/Foo/Bar.pm and load if it exists.
2. If there is a /xao/objects/include configuration or an 'include'
   argument, then check that list of sites for their objects/Foo/Bar.pm
   implementations, returning first found if any.
3. Default to the system XAO::DO::Foo::Bar implementation if none
   are found in site context.

If there is a 'baseobj' argument then the first step is skipped and the search is started with included sites defaulting to the system object.

new (%)

Creates an instance of named object. There is just one required argument - 'objname', everything else is passed into object's constructor unmodified.

AUTHOR

Copyright (c) 2000-2002 XAO Inc.

Andrew Maltsev <am@ejelta.com>.

SEE ALSO

Have a look at: XAO::Web, XAO::Utils, XAO::FS.