NAME

Kernel::System::ModuleAbstraction – Implements module abstraction.

DESCRIPTION

This class implements a mechanism to abstract modules, based on a configurable namespace. The modules inside that namespace are detected by their name and instantiated using Kernel::System::ObjectManager and cached in-memory (Moose attribute). It's also possible to scan the related namespace recursively and instantiate sub-modules with their relative path (relative to the configured namespace).

SYNOPSIS

Assuming we have the module Kernel::System::Example, which wants to load modules from folder structure Kernel::System::Example::*, which contains the Perl modules Example1 and Example2.

Get an instantiated object from the configured namespace.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace => 'Kernel::System::Example',
    );

    my $Example1Object = $Abstraction->Get('Example1');
    $Example1Object = $Abstraction->Get('Example1');    # cached object

Get an instantiated object from the configured namespace but pass parameters to all object constructors.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace    => 'Kernel::System::Example',
        ObjectParams => {
            UserID => 123,
        },
    );

    my $Example1Object = $Abstraction->Get('Example1');
    my $UserID         = $Example1Object->UserID();

Get an instantiated object from the configured namespace but pass parameters to all object constructors and override the parameters for one object.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace    => 'Kernel::System::Example',
        ObjectParams => {
            UserID => 123,
        },
    );

    my $Example1Object = $Abstraction->Get('Example1');
    my $UserID         = $Example1Object->UserID();

    my $Example2Object = $Abstraction->Get(
        'Example2',
        UserID => 234,
    );

    my $UserID = $Example2Object->UserID(); # 234

    # If the object is already cached, the general or custom parameters
    # will be ignored.
    $Example2Object = $Abstraction->Get(
        'Example2',
        UserID => 567,
    );

    $UserID = $Example2Object->UserID(); # object cache, UserID is still 234

Check if a certain module is in namespace.

    if ( $Abstraction->ModuleExists('Example1') ) {
        # Do something.
    }

Check if a certain object was already instantiated and is in cache.

    if ( $Abstraction->ObjectCached('Example1') ) {
        # Do something.
    }

Scan the configured namespace recursively and get an instantiated object from a sub directory.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace => 'Kernel::System::Example',
        Recursive => 1,
    );

    my $Example3Object = $Abstraction->Get('Sub::Example3');
    $Example3Object = $Abstraction->Get('Sub::Example3');    # cached object

As shown in the example, the related sub-modules are referenced from the basic namespace, which means, the relative path has to be added to the module name.

PUBLIC INTERFACE

Provides methods and attributes, to instantiate and preserve objects from a namespace.

has Namespace

The namespace where the modules are located, that can be instantiated.

has Recursive

Indicates if the namespace should be search for modules recursively.

has Ignore

Ignores certain modules by name. The module names are relative to their namespace and must be passed as an array reference.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace => 'Kernel::System::Example',
        Recursive => 1,
        Ignore    => [
            'ExampleModuleName1',
            'Sub::ExampleModuleName2',
            'Sub::Sub::ExampleModuleName3',
        ],
    );

has IgnoreRegex

Ignores certain modules by regular expression. The regular expression must be passed as a simple string and is compared to the found modules including their namespace.

    my $Abstraction = Kernel::System::ModuleAbstraction->new(
        Namespace   => 'Kernel::System::Example',
        Recursive   => 1,
        IgnoreReged => '(Sub::)+Example(1|2)$',
    );

has ObjectParams

Hash reference with object parameters, that will be passed to the constructor of newly instantiated objects. If custom parameters are passed to the Get method, the contents of this attribute will be ignored.

has Modules

Provides the names (absolute path, i.e. Path::To::The::Module) of all modules in the configured namespace. It will be used to detect, if the requested module really exists.

This attributes provides a method ModuleExists to be used to check a module for existence.

    if ( $Abstraction->ModuleExists('My::Abstracted::Module') ) {
        # do something
    }

Please note, that the absolute module path (including the namespace) must be used, just the module name is not enough.

Furthermore the attribute supports a method ModuleList, which returns an array of all modules within the names. The module names in the list contains the related namespace as a prefix.

    (
        My::Abstracted::Module1,
        My::Abstracted::Module2,
        My::Abstracted::Module3,
        ...
    )

Please be aware, that this method returns an unsorted array, instead of an array reference, unlike the attribute ModuleNames, which returns an array reference!

has ModuleNames

Provides an array reference, containing the names of the modules within the given namespace, but without the namespace prefixed to the names, unlike the attribute ModuleList, which returns the absolute namespace of the related modules.

    [
        'Module1',
        'Module2',
        'Sub::Module3',
        'Sub::Sub::Module4',
        ...
    ]

Please note that this list is already sorted alphanumeric.

Get()

Returns cached objects or creates new ones. This method expects at least the name of the module, which should be loaded from the configured namespace.

    $Abstraction->Get('ModuleName')->DoSomething();
    $Abstraction->Get('Sub::ModuleName')->DoSomethingElse();

It is also possible to pass custom module object parameters.

    my $Object = $Abstraction->Get(
        'ModuleName',
        UserID => 123,
        Silent => 1,
    );

If custom parameters are provided, they will be passed to the constructor of the related object to be instantiated (if it's not cached yet). Otherwise object parameters are taken from attribute ObjectParams, if not empty.

PRIVATE INTERFACE

has _Objects

Contains the instantiated objects, that will be re-used, if an already existing one is requested again.

This attribute provides two private methods:

_Set to be used to store an object.

    $Self->_Set( ModuleName => $NewObject );

_Get to get a previously stored object.

    my $Object = $Self->_Get('ModuleName');

and one public method:

ObjectCached to verify if an object is already instantiated and cached.

    my $Boolean = $Self->ObjectCached('ModuleName');