NAME

Kernel::System::ObjectManager – Central singleton manager and object instance generator

SYNOPSIS

    # In top level scripts only!
    local $Kernel::OM = Kernel::System::ObjectManager->new();

    # Everywhere: get a singleton instance (and create it, if needed).
    my $ConfigObject = $Kernel::OM->Get('Kernel::Config');

    # Remove singleton objects and all their dependencies.
    $Kernel::OM->ObjectsDiscard(
        Objects            => ['Kernel::System::Ticket', 'Kernel::System::Queue'],
    );

DESCRIPTION

The ObjectManager is the central place to create and access singleton OTRS objects (via "Get()") as well as create regular (unmanaged) object instances (via "Create()").

How does singleton management work?

It creates objects as late as possible and keeps references to them. Upon destruction the objects are destroyed in the correct order, based on their dependencies (see below).

How to use it?

The ObjectManager must always be provided to OTRS by the top level script like this:

    use Kernel::System::ObjectManager;
    local $Kernel::OM = Kernel::System::ObjectManager->new(
        # possible options for module constructors here
        LogObject {
            LogPrefix => 'OTRS-MyTestScript',
        },
    );

Then in the code any singleton object can be retrieved that the ObjectManager can handle, like Kernel::System::DB:

    return if !$Kernel::OM->Get('Kernel::System::DB')->Prepare('SELECT 1');

Which objects can be loaded?

The ObjectManager can load every object that declares its dependencies like this in the Perl package:

    package Kernel::System::Valid;

    use strict;
    use warnings;

    our @ObjectDependencies = (
        'Kernel::System::Cache',
        'Kernel::System::DB',
        'Kernel::System::Log',
    );

The @ObjectDependencies is the list of objects that the current object will depend on. They will be destroyed only after this object is destroyed (only for singletons).

If you want to signal that a package can NOT be loaded by the ObjectManager, you can use the $ObjectManagerDisabled flag:

    package Kernel::System::MyBaseClass;

    use strict;
    use warnings;

    our $ObjectManagerDisabled = 1;

There are a few flags available to convey meta data about the packages to the object manager.

To indicate that a certain package can only be loaded as a singleton, you can use the IsSingleton flag. Similarly, you can indicate that a certain package can only be created as unmanaged instance, and not as a singleton via the NonSingleton flag. By default, the ObjectManager will die if a constructor does not return an object. To suppress this in the "Create()" method, you can use the AllowConstructorFailure flag (this will not work with "Get()").

    package Kernel::System::MyPackage;

    use strict;
    use warnings;

    our %ObjectManagerFlags = (
        IsSingleton             => 1,  # default 0
        NonSingleton            => 0,  # default 0
        AllowConstructorFailure => 0,  # default 0
    );

PUBLIC INTERFACE

new()

Creates a new instance of Kernel::System::ObjectManager.

This is typically only needed in top level (bin/) scripts! All parts of the OTRS API assume the ObjectManager to be present in $Kernel::OM and use it.

Sometimes objects need parameters to be sent to their constructors, these can also be passed to the ObjectManager's constructor like in the following example. The hash reference will be flattened and passed to the constructor of the object(s).

    local $Kernel::OM = Kernel::System::ObjectManager->new(
        Kernel::System::Log => {
            LogPrefix => 'OTRS-MyTestScript',
        },
    );

Alternatively, "ObjectParamAdd()" can be used to set these parameters at runtime (but this must happen before the object was created).

If the Debug => 1 option is present, destruction of objects is checked, and a warning is emitted if objects persist after the attempt to destroy them.

Get()

Retrieves a singleton object, and if it not yet exists, implicitly creates one for you.

    my $ConfigObject = $Kernel::OM->Get('Kernel::Config');

    # On the second call, this returns the same ConfigObject as above.
    my $ConfigObject2 = $Kernel::OM->Get('Kernel::Config');

Create()

Creates a new object instance. This instance will not be managed by the object manager later on.

    my $DateTimeObject = $Kernel::OM->Create('Kernel::System::DateTime');

    # On the second call, this creates a new independent instance.
    my $DateTimeObject2 = $Kernel::OM->Create('Kernel::System::DateTime');

It is also possible to pass in constructor parameters:

    my $DateTimeObject = $Kernel::OM->Create(
        'Kernel::System::DateTime',
        ObjectParams => {
            Param1 => 'Value1',
        },
    );

By default, this method will die, if the package cannot be instantiated or the constructor returns undef. You can suppress this with Silent => 1, for example to not cause exceptions when trying to load modules based on user configuration.

    my $CustomObject = $Kernel::OM->Create(
        'Kernel::System::CustomObject',
        Silent => 1,
    );

ObjectInstanceRegister()

Adds an existing object instance to the ObjectManager so that it can be accessed by other objects.

This should only be used on special circumstances, e. g. in the unit tests to pass $Self to the ObjectManager so that it is also available from there as 'Kernel::System::UnitTest'.

    $Kernel::OM->ObjectInstanceRegister(
        Package      => 'Kernel::System::UnitTest',
        Object       => $UnitTestObject,
        Dependencies => [],         # optional, specify OM-managed packages that the object might depend on
    );

ObjectParamAdd()

Adds arguments that will be passed to constructors of classes when they are created, in the same format as the new() method receives them.

    $Kernel::OM->ObjectParamAdd(
        'Kernel::System::Ticket' => {
            Key => 'Value',
        },
    );

To remove a key again, send undef as a value:

    $Kernel::OM->ObjectParamAdd(
        'Kernel::System::Ticket' => {
            Key => undef,               # this will remove the key from the hash
        },
    );

ObjectsDiscard()

Discards internally stored objects, so that the next access to objects creates them newly. If a list of object names is passed, only the supplied objects and their recursive dependencies are destroyed. If no list of object names is passed, all stored objects are destroyed.

    $Kernel::OM->ObjectsDiscard();

    $Kernel::OM->ObjectsDiscard(
        Objects            => ['Kernel::System::Ticket', 'Kernel::System::Queue'],

        # optional
        # forces the packages to be reloaded from the file system
        # sometimes necessary with mod_perl when running CodeUpgrade during a package upgrade
        # if no list of object names is passed, all stored objects are destroyed
        # and forced to be reloaded
        ForcePackageReload => 1,
    );

Mostly used for tests that rely on fresh objects, or to avoid large memory consumption in long-running processes.

Note that if you pass a list of objects to be destroyed, they are destroyed in in the order they were passed; otherwise they are destroyed in reverse dependency order.