Did you spot something wrong or missing on this page? If you have an account on this TWiki, you can fix it yourself by editing the page. If you don't have an account, you can leave a message at the bottom of the page to tell us about it. Thank you in advance!

The extension registry

You must register your contribution (whether it is a tool, perspective, view, component to views or component to the editor area) to HIPE to make it part of the application. Registering means that you have to write add an entry to the jython package module (aka __init__.py) within the sub-system that is under your control.

This section explains the workings of the registry works and how it can automatically find your contribution.

Introduction

The registry mechanism relies on the recursive reading of the jython package modules built into the HCSS. The application will execute the following line:

from herschel.all import *

That line will read sub-packages (share, ia, spire, hifi, pacs) which read their sub-packages and so forth. At some point the init.py of your sub-system is read. This of course only works if the relevant init.py and optionally the all.py files are provided in these packages. Discussion of the workings of these files fall outside the scope of this document.

The idea is that in such a file you call the ExtensionRegistry singleton and add your contribution to it as follows:

ExtensionRegistry.getInstance().register(CLASSIFICATION, Extension(...))

where CLASSIFICATION is one of (pre-defined):

• ExtensionRegistry.COMPONENT adds a new component to some factory.
• ExtensionRegistry.FACTORY adds a new factory.
• ExtensionRegistry.VIEW adds a new view.
• ExtensionRegistry.PERSPECTIVE adds a new perspective.

or a new type if you deem it necessary.

To keep the code readable, we recommend you to use temporary aliases, which you should clean-up afterwards:

# short-cuts
from herschel.ia.gui.kernel import ExtensionRegistry, Extension
REGISTRY  = ExtensionRegistry.getInstance()
COMPONENT = ExtensionRegistry.COMPONENT

# registry
REGISTRY.register(COMPONENT, Extension(...))
REGISTRY.register(COMPONENT, Extension(...))
REGISTRY.register(COMPONENT, Extension(...))
REGISTRY.register(COMPONENT, Extension(...))
REGISTRY.register(COMPONENT, Extension(...))
REGISTRY.register(COMPONENT, Extension(...))

# clean-up
del(ExtensionRegistry, Extension, REGISTRY, COMPONENT)

The registry mechanism is made loosely in such way that it does not matter in which order the packages are read (and therefor the extensions are being added). At run-time all extensions are read first; once done it starts interpreting the contents of the registry.

Extension API

The Extension class is a very simple class with a constructor that takes four String arguments (TODO expand it):

Extension(id, class, arg1, arg2)

where:

• id is a unique ID for this extension.
• class is the java class definition.

The meaning of arg1 and arg2 varies depending on the classification of the extension.

Perspective Extension

arg1	Human readable title of the perspective as it should appear in the menu, e.g. "Hello World"
arg2	Resource location of a 16x16 Icon for this perspective, e.g. "herschel/spire/icon/hello.gif" or None

An example for the JIDE perspective:

Extension("site.perspective.classic",
          "herschel.ia.gui.apps.perspectives.ClassicPerspective",
          "Classic (JIDE)",
          None));

View Extension

arg1	Human readable title of the view as it should appear in the menu and in the title bar of the view, e.g. "Hello World"
arg2	Resource location of a 16x16 Icon for this view, e.g. "herschel/spire/icon/hello.gif" or None

An example for the Console View:

Extension("site.view.console",
          "herschel.ia.jconsole.views.ConsoleView",
          "Console",
          "herschel/ia/gui/kernel/icons/Console.gif"));

Factory Extension

If views are using extendable factories, the API of that view should provide sufficient information about how to add factories. Typically views use factories whenever that view needs to react on a user selection, for example a user selects a variable and that view should show something about that variable. In that case the variable selection is coupled to a factory in that specific view such that other contributors can contribute a component for new types of variables.

An example is the Outline View. It currently can respond to selections of variables, but it could respond to other types of selections such as tools. For that it uses factories for which applies:

arg1	Specifies the type (class definition) of the selection
arg2	Specifies the unique ID of the view that this factory belongs to

For variable selections, a factory is defined:

Extension("factory.outline.variable",
          "herschel.ia.gui.kernel.VariableSelectionFactory",
          "herschel.ia.gui.kernel.VariableSelection",
          "site.view.outline")

Component Extension

Contributors can add components to existing factories. Taking the example of the "factory.outline.variable" factory that coupled to the Outline View, the syntax of an extension becomes as follows:

arg1	Specifies the unique ID of the factory to which this component belongs to
arg2	Specifies class definition of the object that this component can show

An example of such a component:

Extension("herschel.ia.gui.apps.components.outline.ProductOutline",
          "herschel.ia.gui.apps.components.outline.ProductOutline",
          "factory.outline.variable",
          "herschel.ia.dataset.Product")

It is a component that shows structure of a Product within the Outline View.

Note that for Factory Extensions, arg1 is a classname and arg2 is the ID of the view the factory belongs to. For Component Extensions, arg1 is the ID of the factory and arg2 is a classname. These feel switched with respect to each other, so check the definitions carefully.

See also the component contribution pages.