Feature Request: Configuration Facility

[jri]

Plugin developers must be able to attach configuration information to arbitrary objects.

Configuration information must be configurable itself, in terms of 1) type/structure, 2) default values, and 3) allowed modifier roles (Admin, Creator, Owner, Member).

The Webclient could offer functionality to edit configuration information.
Configuration information must also be changed programmatically.

Configuration information must survive a plugin resp. platform update.

[Jörg Richter <jri@…>]

In 6ae66671aff158daf23bc3de62ec052056b6f613/deepamehta:

New module: dm4-config (#830).

1st data model and REST service.

See #830.

[Jörg Richter <jri@…>]

In eb96c8175fe221dc3a21abd6bcaffd57c091d1c9/deepamehta:

Config plugin: add "Configure" command (#830).

The Webclient shows a "Configure" command in the topic context menu if configuration definitions have been registered. THe "Configure" command features a submenu which lists all the registered config types. Once a config type is selected the corresponding config topic is (created if not yet exists and then) revealed, ready for being edited in the detail panel.

See #830.

[Jörg Richter <jri@…>]

In f0c7de481dec0d6f363c80593027f6f35354d0bc/deepamehta:

Config plugin: support ADMIN role (#830, #812).

Config modification role ADMIN is now supported: Config topics defined with that role can only be modified by admins.

The remaining config modification roles (CREATOR, OWNER, MEMBER) are not yet supported.

Files plugin: the individual (per-user) disk quota can be modified by admins only.

See #830.
See #812.

[Jörg Richter <jri@…>]

In 054aa1e296b55585f72c409fda772da3e99e0857/deepamehta:

Config module: by topic-uri configs (#830).

TopicConfigDefinition now supported by Webclient.

See #830.

[Jörg Richter <jri@…>]

In 062d9afc6f4f732e1fb4169be777ba2c836dda23/deepamehta:

Drop lazy config topic creation (#830).

Now the Config module attaches all config topics to every newly created topic immediately.

CHANGES

Config API:

1 new method:

createConfigTopic(String configTypeUri, Topic topic)

To be used in migrations to attach a config topic to existing topics.

See #830.

[Jörg Richter <jri@…>]

In abfadc5d89dd3dd9aeb4eeacdea36aaf102d5e72/deepamehta:

Config service: refactor ConfigDefinition? (#830).

Enum ConfigTarget replaces the 2 ConfigDefinition subclasses.
The ConfigDefinition constructor has changed accordingly.

See #830.

[Jörg Richter <jri@…>]

In e0abaf2e6f7c656782365c27be198cb054920f06/deepamehta:

Add migrations to create config topics (#830).

Equip the Access Control and Files plugins with migrations to create default config topics ("Login enabled", "Disk Quota") for existing user accounts when UPDATING a DM installation.

See #830.

[Jörg Richter <jri@…>]

In 31daf3fdc8b25b1de7c4f17ac58742f74dc0da04/deepamehta:

Set color for "Configuration" assoc type (#830).

See #830.

[Jörg Richter <jri@…>]

In 48d06ee26f1cf947662388ed589edf72b1bd6af6/deepamehta:

Config module: privileged getConfigTopic() (#830).

Getting a configuration topic is a privileged operation, it bypasses the access control system.

See #830.

[Jörg Richter <jri@…>]

In c4c57a5b9bbe612eb6cd7062783094f1ab76b1a0/deepamehta:

Config module: rename "Configure" command (#830).

... to "Show Configuration" as this is what the submenu items acutually do: they just *show*/*reveal* the respective config topic. *Configure* would only be the proper term if the user has permission to *edit* the config topic.

See #830.

[jri]

Plugins who register a config definition must be able to customize the config value dynamically, that is before the Config plugin sets the default value. This is required in conjunction with #849.

[Jörg Richter <jri@…>]

In 63689801ddd64013919c7003c9dc6251ed34565b/deepamehta:

Config plugin: add ConfigCustomizer? (#830).

When registering a config definition a plugin can supply a ConfigCustomizer in order to adjust the config value dynamically before the Config plugin sets the default value.

See #830.

[jri]

When using the "Show Configuration" command to reveal a composite config topic, its child values are not displayed in the detail panel.

[Jörg Richter <jri@…>]

In 7c342758a351a04fe69dc4311a0df2880ef3fa71/deepamehta:

Config: fix reveal composite config topic (#830).

When using the "Show Configuration" command to reveal a composite config topic, its child values are displayed in the detail panel.

Close #830.

[Malte]

It would be nice if you could share some info about on how to use this new facility, esp. on the the questions:

1) how to make use of these "configuration topics" to store "private per-user" options, like e.g. mail credentials
2) and how the task of introducing those into an existing DB of users can be accomplished

This knowledge would have immediate effect on various modules, esp. on advancing #822.
Thanks for your support!

[jri]

Replying to Malte:

It would be nice if you could share some info about on how to use this new facility

Sure!
I'll write a how-to very soon.
Please be patient :-)

[jri]

The Config Service

The Config Service helps plugin developers with attaching configuration information to topics.

The Config Service is provided by the Config plugin. The sources are located in modules/dm4-config/. The bundle is named deepamehta-config-4.7.jar.

The Config Service is introduced in DM 4.7 and extended in DM 4.8. This guide applies to DM 4.7.

Concept

The developer registers a Config Definition to describe the relation between topics and their configuration information. Every time the user (or the system) creates a topic the Config Service looks if matching Config Definitions are registered, and if so attaches the default configuration to the created topic. Thus the Config Service ensures that every topic gets its configuration information automatically.

A Config Definition contains the following information:

• What is the Target of this definition? That is which topic(s) are to be configured? E.g. you can say "All Username topics" or "The Mail plugin".
• What is the default configuration information? E.g. you can say "the default disk quota (for every user) is 150 MB".
• Who is permitted to change a topic's configuration information? E.g. you can say "Only administrators", or "Only the creator of the topic".

Configuration information have itself the form of topics. These Config Topics can have any type. The plugin developer is free to define arbitrary Config Types (simple or composite). E.g. the Files plugin defines a (simple) Config Type dm4.files.disk_quota.

As configuration information are usual topics you can edit them in the Webclient by the usual means. The Config plugin puts a "Show Configuration" command in the Webclient's topic context menu. Its submenu lists all the Config Types which are applicable to the clicked topic, according to the registered Config Definitions. Once selected the corresponding Config Topic is revealed, ready for being edited, provided you have the permission to do so.

Using the Config Service

The Config Service let you do 3 things:

• Register one or more Config Definitions.
• Get certain configuration information, a Config Topic, that is attached to a particular topic.
• Create Config Topics manually. This is useful when migrating existing content to DM 4.7 (or later).

Registering a Config Definition

The typical form of consuming the Config Service and registering a Config Definition is as follows:

import de.deepamehta.plugins.config.ConfigService;

public class MyPlugin ... {

    @Inject
    private ConfigService configService;

    // --- Plugin hooks ---

    @Override
    public void preInstall() {
        configService.registerConfigDefinition(...);
    }

    @Override
    public void shutdown() {
        // Note 1: unregistering is crucial e.g. for redeploying MyPlugin. The next register call
        // (at preInstall() time) would fail as the Config service already holds such a registration.
        // Note 2: we must check if the Config service is still available. If the Config plugin is redeployed the
        // MyPlugin is stopped/started as well but at shutdown() time the Config service is already gone.
        if (configService != null) {
            configService.unregisterConfigDefinition(...);
        } else {
            logger.warning("Config service is already gone");
        }
    }
}

You see, that you register your Config Definitions in the preInstall() hook and unregister them in the shutdown() hook. The preInstall() hook is useful as it is triggered before your plugin's migration run. This ensures also topics created in migrations possibly gets their configuration information. In the shutdown() hook you should unregister your Config Definitions (see the source comments).

As an example lets see how the Files plugin registers its disk quota Config Definition:

configService.registerConfigDefinition(new ConfigDefinition(
    ConfigTarget.TYPE_INSTANCES, "dm4.accesscontrol.username",
    new TopicModel("dm4.files.disk_quota", new SimpleValue(150)),
    ConfigModificationRole.ADMIN
));

Here the Files plugin basically says to the Config Service: target of this definition are all topic instances of type "Username". The default configuration information is a topic of type "Disk Quota" and a value of 150. Only administrators are permitted to change that value (on a per-username basis).

You see that your plugin can attach configuration information to topics which are defined in other plugins.

The Config related classes are imported from de.deepamehta.plugins.config.

The Config Target

With the Config Target you specify to which topic(s) the Config Definition applies. You can choose between 2 modes:

	applies to ...
ConfigTarget.TYPE_INSTANCES	all instances of a certain type. You specify the type's URI as the 2nd argument.
ConfigTarget.SINGLETON	a single topic, e.g. a Plugin topic. You specify the topic's URI as the 2nd argument.

The Config Modification Role

With the Config Modification Role you specify who is permitted to change a topic's configuration information. The Config Service realizes the permission by assigning the Config Topics it creates to the corresponding workspace. You can choose between 4 values:

	Config Topics Workspace
ConfigModificationRole.ADMIN	"System" workspace
ConfigModificationRole.CREATOR	The private workspace of the topic's creator
ConfigModificationRole.OWNER	The private workspace of the topic's owner
ConfigModificationRole.MEMBER	The workspace the topic is assigned to

NOTE: As of DM 4.7 all roles except ADMIN are not implemented!

to be continued ...

[Malte]

Thanks for this first and in depth explanation of this wonderful new facility.

Just one question for clarification of the term "topic" in the very last table and "Workspace" column: Is the permission to change a topics configuration expressed in the workspace assignment of the so called "target topic" or of the "configuration topic"?

As i understand from this part of the documentation my case is not yet fully supported so my next question consequently is: Can you already give an estimate about when the remainding roles will be implemented?

Ok,thanks for your support!

[jri]

Replying to Malte:

Thanks for this first and in depth explanation of this wonderful new facility.

You're welcome :-)

Just one question for clarification of the term "topic" in the very last table and "Workspace" column: Is the permission to change a topics configuration expressed in the workspace assignment of the so called "target topic" or of the "configuration topic"?

The latter.
The permission to modify a topic is completely independent from the permission to modify a topic's configuration information (= the Config Topics). The topic's workspace assignment is not relevant for the Config Service.

As i understand from this part of the documentation my case is not yet fully supported so my next question consequently is: Can you already give an estimate about when the remainding roles will be implemented?

The remaining roles will be supported in DM 4.8. A rough estimation for the 4.8 release is end of february.