Jump to: navigation, search

Difference between revisions of "Libra/Adopter Guide"

(Adding the editor parts in the adopter's server editor)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Integrating OSGi Framework Editor parts in a WTP server adapter ==
 
== Integrating OSGi Framework Editor parts in a WTP server adapter ==
  
The OSGi Framework Editor feature provides three editor parts that can be integrated in an adopter's WTP server adapter:
+
The ''OSGi Framework Editor'' feature provides three editor parts that can be integrated in an adopter's WTP server adapter:
 
* ''Bundle Information'' - lists all of the bundle in the OSGi framework, their state and dependencies.
 
* ''Bundle Information'' - lists all of the bundle in the OSGi framework, their state and dependencies.
 
* ''Bundle Dependency Graph'' - displays the bundle dependencies as a graph.  
 
* ''Bundle Dependency Graph'' - displays the bundle dependencies as a graph.  
Line 62: Line 62:
 
Adding the editor parts to the server editor is just the UI part of the story. The more important (and complex) one is connecting the UI of the editor parts with the state and behavior of the underlying server runtime.
 
Adding the editor parts to the server editor is just the UI part of the story. The more important (and complex) one is connecting the UI of the editor parts with the state and behavior of the underlying server runtime.
  
The editor parts try to adapt the ''IServer'' object to a suitable interface that can feed them with the required data and capabilities.  
+
The editor parts try to adapt the <code>IServer</code> object to a suitable interface that can feed them with the required data and capabilities.  
  
The ''Bundle Information'' and the ''Bundle Dependency Graph'' editor parts adapt the ''IServer'' object to the [https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.core/src/org/eclipse/libra/framework/editor/core/IOSGiFrameworkAdmin.java org.eclipse.libra.framework.editor.core.IOSGiFrameworkAdmin] interface, using a code similar to the one below:
+
The ''Bundle Information'' and the ''Bundle Dependency Graph'' editor parts adapt the <code>IServer</code> object to the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.core/src/org/eclipse/libra/framework/editor/core/IOSGiFrameworkAdmin.java org.eclipse.libra.framework.editor.core.IOSGiFrameworkAdmin]</code> interface, using a code similar to the one below:
  
 
  IOSGiFrameworkAdmin admin = (IOSGiFrameworkAdmin) getServer().getOriginal()
 
  IOSGiFrameworkAdmin admin = (IOSGiFrameworkAdmin) getServer().getOriginal()
 
  .loadAdapter(IOSGiFrameworkAdmin.class, null);
 
  .loadAdapter(IOSGiFrameworkAdmin.class, null);
  
The ''Server Console'' editor parts adapts the ''IServer'' object to the [https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.core/src/org/eclipse/libra/framework/editor/core/IOSGiFrameworkConsole.java org.eclipse.libra.framework.editor.core.IOSGiFrameworkConsole] interface, using a code similar to the one below:
+
The ''Server Console'' editor parts adapts the <code>IServer</code> object to the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.core/src/org/eclipse/libra/framework/editor/core/IOSGiFrameworkConsole.java org.eclipse.libra.framework.editor.core.IOSGiFrameworkConsole]</code> interface, using a code similar to the one below:
  
 
  IOSGiFrameworkConsole admin = (IOSGiFrameworkConsole) getServer().getOriginal()
 
  IOSGiFrameworkConsole admin = (IOSGiFrameworkConsole) getServer().getOriginal()
 
  .loadAdapter(IOSGiFrameworkConsole.class, null);
 
  .loadAdapter(IOSGiFrameworkConsole.class, null);
  
The easiest way to make your adopter's WTP server adaptable to the above interfaces is to implement them in the subclass of either the ''ServerDelegate'' or the ''ServerBehaviourDelegate'' classes. There is an excellent example how to do this in the [https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.core/src/org/eclipse/libra/framework/core/OSGIFrameworkInstanceBehaviorDelegate.java OSGIFrameworkInstanceBehaviorDelegate] of Libra Launchers.
+
The easiest way to make your adopter's WTP server adaptable to the above interfaces is to implement them in the subclass of either the <code>ServerDelegate</code> or the <code>ServerBehaviourDelegate</code> classes. There is an excellent example how to do this in the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.core/src/org/eclipse/libra/framework/core/OSGIFrameworkInstanceBehaviorDelegate.java OSGIFrameworkInstanceBehaviorDelegate]</code> class of OSGi Framework Launchers.
  
The most tricky part is the implementation of the <code>IOSGiFrameworkAdmin.getBundles()</code> method.
+
The most tricky part is the implementation of the <code>IOSGiFrameworkAdmin.getBundles()</code> method. It returns a <code>Map<Long, IBundle></code> that is a collections of <code>IBundle</code> objects that represents the OSGi bundles with their state and dependencies. The <code>IBundle</code> interface references several other interfaces for package and service dependencies. All these interfaces from the <code>[https://github.com/eclipse/libra/tree/master/plugins/org.eclipse.libra.framework.editor.core/src/org/eclipse/libra/framework/editor/core/model org.eclipse.libra.framework.editor.core/model]</code> must be also implemented by the adopter.
 +
 
 +
=== Using the OSGi JMX Management Model for integration ===
 +
 
 +
Fortunately, the ''OSGi Framework Editor'' feature contains a plug-in - ''[https://github.com/eclipse/libra/tree/master/plugins/org.eclipse.libra.framework.editor.integration org.eclipse.libra.framework.editor.integration]'' - that provides a basic, yet fully functional, implementation for integrating the editor parts with an OSGi runtime.
 +
 
 +
The ''Bundle Information'' and ''Bundle Dependency Graph'' editor parts can retrieve the necessary information from the OSGi framework through the standard OSGi JMX Management Model. The implementation is provided with the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.integration/src/org/eclipse/libra/framework/editor/integration/admin/osgijmx/OSGiJMXFrameworkAdmin.java org.eclipse.libra.framework.editor.integration.admin.osgijmx.OSGiJMXFrameworkAdmin]</code> class.
 +
 
 +
For the ''Server Console'' editor part this plug-in provides a very simple implementation that writes the shell command to the standard input of the OSGi Framework process and reads the result from the standard output. The implementation is provided with the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.editor.integration/src/org/eclipse/libra/framework/editor/integration/console/basic/BasicOSGiFrameworkConsole.java org.eclipse.libra.framework.editor.integration.console.basic.BasicOSGiFrameworkConsole]</code> class.
 +
 
 +
The best source for learning how to use the integration plug-in is by taking a look how it is used in the OSGi Framework Launchers server adapters and the <code>[https://github.com/eclipse/libra/blob/master/plugins/org.eclipse.libra.framework.core/src/org/eclipse/libra/framework/core/OSGIFrameworkInstanceBehaviorDelegate.java OSGIFrameworkInstanceBehaviorDelegate]</code> class in particular.
 +
 
 +
{{note|Take a look at the [[Libra/User_Guide#Configuring_the_Bundle_Information_and_Bundle_Dependency_Graph_editor_parts|User Guide]] for instruction how to configure the OSGi JMX Management Model provided by the integration plug-in.}}
 +
 
 +
=== Exemplary integrations ===
 +
 
 +
The best source for learning is by taking a look at code that already integrates the editor parts. There are two server adapters in Eclipse projects that integrate the editor parts:
 +
* OSGi Framework Launchers - this one was already mentioned in the previous sections. It uses the standard OSGi JMX Management Model implementation provided by the [https://github.com/eclipse/libra/tree/master/plugins/org.eclipse.libra.framework.editor.integration integration plug-in].
 +
* [[Virgo/Tooling|Virgo Tooling]] - this is the origin of the editor parts that were moved to the Libra project. The integration between the UI and the server runtime is also done through JMX, but is specific to the Virgo server. This [https://github.com/kaloyan-raev/virgo.ide/commit/665cf74f67221d612e05e7e6d389a9175d4c8c75 changelist] can shows how the Virgo Tooling integrates the editor parts from Libra.

Latest revision as of 09:01, 23 October 2011

Integrating OSGi Framework Editor parts in a WTP server adapter

The OSGi Framework Editor feature provides three editor parts that can be integrated in an adopter's WTP server adapter:

  • Bundle Information - lists all of the bundle in the OSGi framework, their state and dependencies.
  • Bundle Dependency Graph - displays the bundle dependencies as a graph.
  • Server Console - allows users to execute commands on the running server and see the result.

Adding the editor parts in the adopter's server editor

Each of the editor parts can be added as an additional tab to the server editor of the adopter's WTP server adapter. Adopters can choose to either add all three of them, or just the ones they would like.

This can be done by using the org.eclipse.wst.server.ui.editorPages extension point.

Below are given example usages of this extension point for Libra Launchers.

  • for the Bundle Information editor part:
  <extension
        point="org.eclipse.wst.server.ui.editorPages">
     <page
           class="org.eclipse.libra.framework.editor.ui.overview.BundleInformationEditorPage"
           id="org.eclipse.libra.framework.editor.integration.bundleInformation"
           name="Bundle Overview"
           order="30"
           typeIds="org.eclipse.libra.framework.*">
     </page>
  </extension>
  • for the Bundle Dependency Graph editor part:
  <extension
        point="org.eclipse.wst.server.ui.editorPages">
     <page
           class="org.eclipse.libra.framework.editor.ui.dependencies.BundleDependencyEditorPage"
           id="org.eclipse.libra.framework.editor.integration.bundleDependency"
           name="Bundle Dependency Graph"
           order="40"
           typeIds="org.eclipse.libra.framework.*">
     </page>
  </extension>
  • for the Server Console editor part:
  <extension
        point="org.eclipse.wst.server.ui.editorPages">
     <page
           class="org.eclipse.libra.framework.editor.ui.console.ServerConsoleEditorPage"
           id="org.eclipse.libra.framework.editor.integration.serverConsole"
           name="Console"
           order="50"
           typeIds="org.eclipse.libra.framework.*">
     </page>
  </extension>

In the above examples only the class attribute is mandatory to point to the given value. The typeIds must match the server type id of the adopter's WTP server. All other attribute can be customized to values that best fit the adopter's needs. For detailed description of available attributes and their usage consult the description of the extension point.

The described contributions to the org.eclipse.wst.server.ui.editorPages extension point will only work if the respective packages are imported as dependencies to the contributing plug-in. Here are the necessary imports in the META-INF/MANIFEST.MF:

Import-Package: org.eclipse.libra.framework.editor.ui.console;version="[0.1.0,2.0.0)",
 org.eclipse.libra.framework.editor.ui.dependencies;version="[0.1.0,2.0.0)",
 org.eclipse.libra.framework.editor.ui.overview;version="[0.1.0,2.0.0)"

Connecting the editor parts with the server runtime

Adding the editor parts to the server editor is just the UI part of the story. The more important (and complex) one is connecting the UI of the editor parts with the state and behavior of the underlying server runtime.

The editor parts try to adapt the IServer object to a suitable interface that can feed them with the required data and capabilities.

The Bundle Information and the Bundle Dependency Graph editor parts adapt the IServer object to the org.eclipse.libra.framework.editor.core.IOSGiFrameworkAdmin interface, using a code similar to the one below:

IOSGiFrameworkAdmin admin = (IOSGiFrameworkAdmin) getServer().getOriginal()
	.loadAdapter(IOSGiFrameworkAdmin.class, null);

The Server Console editor parts adapts the IServer object to the org.eclipse.libra.framework.editor.core.IOSGiFrameworkConsole interface, using a code similar to the one below:

IOSGiFrameworkConsole admin = (IOSGiFrameworkConsole) getServer().getOriginal()
	.loadAdapter(IOSGiFrameworkConsole.class, null);

The easiest way to make your adopter's WTP server adaptable to the above interfaces is to implement them in the subclass of either the ServerDelegate or the ServerBehaviourDelegate classes. There is an excellent example how to do this in the OSGIFrameworkInstanceBehaviorDelegate class of OSGi Framework Launchers.

The most tricky part is the implementation of the IOSGiFrameworkAdmin.getBundles() method. It returns a Map<Long, IBundle> that is a collections of IBundle objects that represents the OSGi bundles with their state and dependencies. The IBundle interface references several other interfaces for package and service dependencies. All these interfaces from the org.eclipse.libra.framework.editor.core/model must be also implemented by the adopter.

Using the OSGi JMX Management Model for integration

Fortunately, the OSGi Framework Editor feature contains a plug-in - org.eclipse.libra.framework.editor.integration - that provides a basic, yet fully functional, implementation for integrating the editor parts with an OSGi runtime.

The Bundle Information and Bundle Dependency Graph editor parts can retrieve the necessary information from the OSGi framework through the standard OSGi JMX Management Model. The implementation is provided with the org.eclipse.libra.framework.editor.integration.admin.osgijmx.OSGiJMXFrameworkAdmin class.

For the Server Console editor part this plug-in provides a very simple implementation that writes the shell command to the standard input of the OSGi Framework process and reads the result from the standard output. The implementation is provided with the org.eclipse.libra.framework.editor.integration.console.basic.BasicOSGiFrameworkConsole class.

The best source for learning how to use the integration plug-in is by taking a look how it is used in the OSGi Framework Launchers server adapters and the OSGIFrameworkInstanceBehaviorDelegate class in particular.

Note.png
Take a look at the User Guide for instruction how to configure the OSGi JMX Management Model provided by the integration plug-in.


Exemplary integrations

The best source for learning is by taking a look at code that already integrates the editor parts. There are two server adapters in Eclipse projects that integrate the editor parts:

  • OSGi Framework Launchers - this one was already mentioned in the previous sections. It uses the standard OSGi JMX Management Model implementation provided by the integration plug-in.
  • Virgo Tooling - this is the origin of the editor parts that were moved to the Libra project. The integration between the UI and the server runtime is also done through JMX, but is specific to the Virgo server. This changelist can shows how the Virgo Tooling integrates the editor parts from Libra.