DpHipeRegistry < Public

Public Web>DpHipe>DpHipeRegistry (2014-02-19, AlvarGarcia) (raw view)
<!-- ANALYTICS CODE - DO NOT EDIT -->
%INCLUDE{"%ATTACHURL%/GoogleAnalytics.txt" raw="on"}%
<!-- END OF ANALYTICS CODE -->
<!--
   * Set TOPICTITLE = The extension registry
-->

| *PDF Version* | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=portrait&pdftoclevels=2][Portrait]] | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=landscape&pdftoclevels=2][Landscape]] |

%ICON{"help"}% *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

%STARTINCLUDE%
<!-- summary -->
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.
%STOPINCLUDE%

%TOC%

%STARTSECTION{"contrGuide"}%

<br clear="all"/>


<!--
   Some short-cuts
   * Set VIEWABLE   = Viewable
   * Set VIEWPART   = !ViewPart
   * Set JCOMPONENT = [[Java2Api:javax/swing/JComponent.html][javax.swing.JComponent]]
   * Set REGISTRY   = [[DpHipeRegistry][Extension Registry]]
   * Set INIT_PY    = __init__.py
   * Set SELISTENER = !SiteEventListener

   * Set EXTENSION_REGISTRY= ==ExtensionRegistry==
   * Set EXTENSION         = Extension
   * Set VARIABLES_VIEW    = !VariablesView
   * Set OUTLINE_VIEW      = !OutlineView
   * Set OUTLINE_COMPONENT = !OutlineComponent
   * Set EDITOR_COMPONENT  = !EditorComponent
   * Set SELECTION_EVENT   = !SelectionEvent
   * Set FINE_TIME         = !FineTime
   * Set EXPLORER          = Explorer
-->

---++ Introduction
<blockquote>
The registry mechanism relies on the recursive reading of the jython package modules built into the HCSS. The application will execute the following line:
<pre>
from herschel.all import *
</pre>
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 %EXTENSION_REGISTRY% singleton and add your contribution to it as follows:
<pre>
ExtensionRegistry.getInstance().register(CLASSIFICATION, Extension(...))
</pre>
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:
<pre>
# 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)
</pre>

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.
</blockquote>

---++ Extension API
<blockquote>
The %EXTENSION% class is a very simple class with a constructor that takes four ==String== arguments (_TODO_ expand it):
<pre>
Extension(id, class, arg1, arg2)
</pre>

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
<blockquote>
| ==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_:
<pre>
Extension("site.perspective.classic",
          "herschel.ia.gui.apps.perspectives.ClassicPerspective",
          "Classic (JIDE)",
          None));
</pre>
</blockquote>

---+++ View Extension
<blockquote>
| ==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_:
<pre>
Extension("site.view.console",
          "herschel.ia.jconsole.views.ConsoleView",
          "Console",
          "herschel/ia/gui/kernel/icons/Console.gif"));
</pre>
</blockquote>

---+++ Factory Extension
<blockquote>
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:
<pre>
Extension("factory.outline.variable",
          "herschel.ia.gui.kernel.VariableSelectionFactory",
          "herschel.ia.gui.kernel.VariableSelection",
          "site.view.outline")
</pre>

</blockquote>


---+++ Component Extension
<blockquote>
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:
<pre>
Extension("herschel.ia.gui.apps.components.outline.ProductOutline",
          "herschel.ia.gui.apps.components.outline.ProductOutline",
          "factory.outline.variable",
          "herschel.ia.dataset.Product")
</pre>
It is a component that shows structure of a Product within the Outline View.

%ICON{"warning"}% 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 [[DpHipeComponents][component contribution]] pages.
</blockquote>


</blockquote>

%ENDSECTION{"contrGuide"}%

<!-- Author: Main.JorgoBakker -->

<!--
   * Set ALLOWTOPICCHANGE = Main.RegisteredUsersGroup, Main.TWikiAdminGroup
-->

<hr/>
<!-- COMMENT BOX CODE - DO NOT EDIT -->
<div id="disqus_thread"></div>
<script type="text/javascript">
    var disqus_shortname = 'herscheltwiki'; // required: replace example with your forum shortname

    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">blog comments powered by <span class="logo-disqus">Disqus</span></a>
<!-- END OF COMMENT BOX CODE -->
<hr/>
Topic revision: r13 - 2014-02-19 - AlvarGarcia
Public
Webs
Public
TWiki