HomeDownloadsUser GuideDevelopment

Editor: Editor Configuration

The editor configuration uses a custom plug-in mechanism based on the PicoContainer IoC container.

Configuration File

At startup the editor loads the configuration file configuration.xml. This file has to be located on the toplevel somewhere on the classpath.

The editor has a default configuration included in its JAR file, either replace it with your custom version or better bundle your extensions and plugins in a custom JAR file that is listed first on the classpath..

Sections

The configuration file is divided into several sections and roughly has the following structure:

<?xml version="1.0"?>
<configuration>

  <generic>
    <!-- Describes generic policy elements, support classes and plugins for the GUI. -->
    <policy>
      <!-- Factory classes, instances are not cached. -->
      <policy-component class="..."/>
      <policy-component class="..."/>
      <support-component class="..."/>
    </policy>
    <plugins>
      <!-- Instances are unique and cached. -->
      <plugin class="..."/>
      <plugin class="..."/>
    </plugins>
  </generic>

  <editors>
    <!-- Contains presenters and views for policy elements that can be edited. -->
    <editor-presenters>
      <!-- Factory classes, instances are not cached. -->
      <editor-presenter type="..." class="..."/>
      <editor-presenter type="..." class="..."/>
    </editor-presenters>
    <editor-views>
      <!-- Factory classes, instances are not cached. -->
      <editor-view type="..." class="..."/>
      <editor-view type="..." class="..."/>
    </editor-views>
  </editors>

  <tools>
    <!-- Describes presenters and views used for tools to edit policies. -->
    <tool-presenters>
      <!-- Factory classes, instances are not cached. -->
      <tool-presenter class="..."/>
      <tool-presenter class="..."/>
    </tool-presenters>
    <tool-views>
      <!-- Instances are unique and cached. -->
      <tool-view class="..."/>
      <tool-view class="..."/>
    </tool-views>
  </tools>

</configuration>

There are three toplevel sections:

  • Generic
    Describes generic policy elstrongents, support classes and plugins for the GUI.
  • Editors
    Contains presenters and views for policy elstrongents that can be edited.
  • Tools
    Describes presenters and views used for tools to edit policies.

The toplevel sections are only used for logical grouping. They do not have any attributes or factory/instance elements that are used.

Factory Classes vs. Instances

In the above outline there are comments mentioning factory classes and instances. The configuration trader makes a distinction about classes which are only instantiated once and then reused and classes which are instantiated whenever they are used. The purpose of this distinction is to let the configuration trader either act as a factory or as a product trader at the same time depending on the needs of the application.

What sounds complicated in theory is very simple in practice, for example:

  • Tools are used to provide general helper functionality or outline views for the currently active policy. They are always around, independently if there is a policy loaded or not. Therefore it makes sense if you think about a tool like e.g. the one that displays a list of recently loaded files that it only exists once and that whenever somebody wants to talk to this tool he will talk to the singleton instance.
  • Editors for elements stored in a policy, like e.g. an editor for a target access rule are specific to the target access rule being edited. Because there can be several editors of the same kind opened at the same time it makes sense that those editors are created whenever they are needed.
  • Plugins on the other hand, like for example the plugin that handles imports of the actions stored in a WSDL file do not need to be recreated each time. It suffices if there is only one instance of such a plugin around. This also simplifies including the plugin actions in the menu bar and tool bar.

    Support classes that are used by plugins on the other hand are probably task and plugin specific and will be instantiated each time they are needed. Those should be placed in the support section of the policy toplevel section.

In the end checking out the existing plugins, editors, tools and support classes will give you a better idea and understanding where to place your extension in the configuration file than writing a heap load of documentation. Please use the source and check out what is there to get an idea.

Element Names And Attributes

Except for the top two levels of section names (i.e. generic, policy, plugins, editors, editor-presenters, editor-views, tools>, tool-presenters, tool-views) the element names are ignored while parsing. The only thing which is important that the elements on the third level are all parsed to look for classes to be included in the configuration container.

Elements on the third level (like policy-component, support-component, plugin, editor-presenter, editor-view, tool-presenter, tool-view) are scanned for an attribute named "class" wich should contain the fully qualified classname of a component to be included in the configuration pico container.

Some elements also feature an "type" attribute which means that the component will be added for a specific type in the container, e.g. a presenter for a DomainBean or for a TargetBean. Check out the existing configuration files and you will get a feeling where and why the "type" attribute is used.

Please note that the "class" and "type" attributes are the only ones read by the standard configuration trader. Are other attributes may be used to customize your components as described in the next section.

Customizing Your Plugins

The configuration trader provides an easy yet flexible way to customize your plugins by means of XML attributes. There is no fixed rule what kind of attributes you should choose or what the content should be. After all the mechanism was designed to be easily implemented and just do its job.

To access the attribute values stored in the configuration file you can use the following method on the org.openpermis.editor.policy.configuration.Configuration instance that was injected to your plugin:

Example configuration:

<?xml version="1.0"?>
<configuration>
  <generic>
    ...
    <plugins>
    ...
      <plugin class="org.test.MyPlugin" mode="Verbose"/>
    ...
    </plugins>
  </generic>
  ...
</configuration>

Example plugin:

package org.test;

import org.openpermis.editor.policy.configuration.Configuration;

public class MyPlugin {
  public MyPlugin (Configuration configuration) {
    boolean verboseMode = "Verbose".equals(configuration.getSetting("mode"));
    ...
  }
}

Alternatively (if you are a lazy programmer like me) you can simply extend one of the extisting abstract plugin classes and use the configuration offered there.