Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between pages "Execution Environments" and "Adaptor Hooks"

(Difference between pages)
(→‎Standard Execution Environments)
 
 
Line 1: Line 1:
−
==What are Execution Environments?==
+
== Overview ==
 +
Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi Framework.  A framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasks.  A framework adaptor may be used to add functionality to the framework.
  
−
Execution environments (EEs) are symbolic representations of JREs.  For example, rather than talking about a specific JRE, with a specific name at a specific location on your disk, you can talk about the J2SE-1.4 execution environment.  The system can then be configured to use a specific JRE to implement that execution environment.
+
A single framework adaptor is specified when the framework is launched.  By default in Eclipse 3.0 this is set to the EclipseAdaptor. In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations.  This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.
  
−
Execution environments are relevant both to development (compile) time and runtime.  
+
In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor.  The framework adaptor API has remained unchanged for the most part in Eclipse 3.2.  What has changed is the actual implementation of the adaptor API.  A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.
  
−
==So what does this mean to me and my bundles?==
+
== Hookable Adaptor ==
 +
The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor.  This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework.  It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundles.  See the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.
  
−
Good bundles have minimal dependencies.  This allows them to be used in a wider range of situations and results in a smaller overall footprint for applications built of these bundles.  The execution environment needed by your bundle is key in both situations.
+
Framework extension bundles are fragments of the system bundle (org.eclipse.osgi).  As a fragment they can provide extra classes which the framework can use.  A framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file). 
  
−
Consider the different outcomes for some bundle A that requires just Foundation 1.0 and a bundle B that requires J2SE-1.5. First, A can be used in embedded devices where Foundation 1.0 is quite popular.  Second, an application written entirely of bundles such as A can ship on a Foundation 1.0 JRE.  This results in a 40-50MB disk/transfer footprint savings over J2SE-1.5 JREs!
+
=== The Base Adaptor ===
 +
The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor.  This class is used by default as the adaptor of the framework.  You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.
  
−
==Wow! Is this hard to setup?==
+
In some cases it may be impossible to do what you want with the current set of adaptor hooks.  In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementation. If you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.
−
Not really.  [[OSGi | OSGi]] allows bundles to be marked with the minimum execution environment they require (see the [[#Setting the Execution Environment]]).  Setting this value has two effects.
+
−
# The compiler attempts to compile your bundle against the JRE associated with the EE you choose.  For example, if you set your EE to be J2SE-1.3, then the compiler will help you stick to that and not let you use APIs which exist in other class library versions. If you choose to increase your EE level, then you are forced to explicitly do so, rather than finding out later that you did it accidentally by referencing new APIs.
+
−
# The Equinox runtime will refuse to resolve/run your bundle if the current running JRE does not meet the minimum standard you specified.  For example, if you attempt to install bundle B from above (requires J2SE-1.5) on a system running Foundation 1.0, B will not resolve or run.
+
  
−
==Which Execution Environment should I use?==
+
=== The Hook Registry ===
 +
The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework.  When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry.  The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.
  
−
As discussed above, you should seek to use the smallest EE possible. Of course, if you actually need the functionality of J2SE-1.5, you should specify that EE. Remember however that people running on J2SE-1.4, Foundation 1.*, etc. will then not be able to use your bundle.
+
==== Hook Configurators ====
 +
Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interface. Hook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.
  
−
Projects should not leave these choices to chance.  Dependency structures are key parts of an architecture.  For example, the [http://eclipse.org/eclipse Eclipse Project] has explicitly identified EEs for all of their bundles.  These choices are documented in the [http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_2.html#Appendix1 Eclipse 3.2 Plan]. The execution environment listed in the table is based on the needs of the bundle and the expected use scenarios for the bundle.  For example, all of the bundles key to RCP scenarios target only Foundation 1.0.
+
==== Discovering Hook Configurators ====
 +
In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader.  This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle.  Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).
  
−
==Setting the Execution Environment==
+
A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.
−
# Use build N20060420-0010 or later.
+
−
# Right click on your bundle's <tt>MANIFEST.MF</tt> and select '''Open With... > Plug-in Manifest Editor'''.
+
−
# Select the '''Overview''' tab.
+
−
# Note the section in the lower left corner entitled '''Execution Environments'''.
+
−
# Add your appropriate environment(s) noting the [[#Special cases]] below.
+
−
# Save the file.
+
−
# Select the link "update the classpath and compiler compliance settings".
+
−
# Ensure you have no compile errors in your workspace.
+
−
# Release your changes to the repository.
+
  
−
==Special cases==
+
===== hookconfigurators.properties files =====
 +
A hookconfigurators.properties file can be used to declare a list of hook configator classes.  The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes.  For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar:
  
−
===Foundation class libraries===
+
<code>
−
Bundles that require just Foundation 1.0 should in fact list Foundation 1.0 '''and''' J2SE-1.3 in their execution environments. This is because Foundation 1.0 is not a proper subset of 1.3 (it includes some additional javax.microedition classes). Listing them both in essence says that only the intersection of the two EEs is valid for use in the bundle. The situation is the same for Foundation 1.1 and J2SE-1.4.
+
hook.configurators=  
 +
    org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
 +
    org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
 +
    org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
 +
    org.eclipse.core.runtime.internal.stats.StatsManager,
 +
    org.eclipse.osgi.internal.verifier.SignedBundleHook
 +
</code>
  
−
===Compiling against more than is required===
+
Quite a few hook configurators are automatically enabled by default withing the Equinox Framework.  The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator.  All other configurators declared above add extra functionality needed by eclipse and can be disabled.
−
In some cases, a bundle may optionally use function from newer execution environments if available but fall back to some other behaviour if not.  Such bundles must be compiled against the maximum EE actually used in their code.  For instance, the <tt>org.eclipse.osgi</tt> bundle uses <tt>java.nio.*</tt> classes from J2SE-1.4 if available.  It can however run against the OSGI/Minimum-1.0 EE.  As a result, it must be compiled against J2SE-1.4.
+
  
−
In these cases you must list both the EE required for compilation and the absolute minimum EE for runtime in the '''Execution Environment''' section of the bundle '''Overview'''.   The EE needed for compilation against must appear '''first''' in the list. So for <tt>org.eclipse.osgi</tt>, the list (in order) is ''J2SE-1.4'' then ''OSGI/Minimum-1.0''.
+
Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators.  The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.
  
−
===XML and other optional JRE pieces===
+
===== osgi.hook.configurators property =====
−
You must distinguish between core parts of a JRE and optional parts.  For example, the XML support is not a core part of the class libraries in J2SE-1.4.  There are in fact many ways to get XML support added to almost any execution environment.
+
The osgi.hook.configurators configuration property is used to specify the list of hook configurators.  If this property is set then the list of configurators specified will be the only configurators used. If this property is set then the hookconfigurators.properties files will not be processed for additional configurators.  This property can be used in a config.ini to lock down the set of configurators to a specific set.
  
−
While you can gain access to these classes by specifying the related EE, that overly restricts your bundles. The better approach is to ignore this type of class when choosing the minimum EE for your bundle and instead specify Import-Package clauses in the manifest.mf of your bundle.  The IDE and runtime will then find other bundles that export the needed packages and wire the bundles together.
+
===== osgi.hook.configurators.include property =====
 +
The osgi.hook.configurators.include configuration property is used to add additional hook configurators.  This is helpful for configuring optional hook configurators.  Hooks that should be enabled by default should be included in a hookconfigurators.properties file.  This property is ignored if the osgi.hook.configurators is set.
  
−
This approach allows, for example, a bundle listing the J2SE-1.3 EE to use XML function as long as there is another bundle that provides (i.e., exports) the XML APIs.
+
===== osgi.hook.configurators.exclude property =====
 +
The osgi.hook.configurators.include configuration property is used to exclude any hook configurators.  This is helpful for disabling hook configurators that are specified in hook configurator properties files. This property is ignored if the osgi.hook.configurators is set.
  
−
==Managing Execution Environments==
+
== Hook interfaces ==
−
For the most part the Eclipse IDE manages the execution environments for you.  You do however have to have the relevant JREs installed on your machine and configured into your IDE. 
+
  
−
Most JREs can be acquired Sun via their [http://java.sun.com main web site] or their [http://java.sun.com/products/archive/index.html handy archive site].  Note that the best source for suitable Foundation 1.* JREs is IBM's J9.  See [[J9 | Getting J9]] for more details.
+
=== Adaptor Hook ===
  
−
When you install a new JRE, the IDE analyzes the function it provides and identifies the set of EEs it can support.  The IDE distinguishes between '''exact matches''' for an EE and compatible matches.  You can see all the execution environments and the JREs they match by looking at '''Window > Preferences > Java > Installed JREs > Execution Environments'''.
+
=== Bundle File Factory Hook ===
  
−
If you do not have an exact match for an EE that is specified in one of your bundles but do have a compatible match, you get a warning.  Continuing development runs the risk of using API which will not be present at runtime.  If you have neither an exact or compatible match, your bundle's project will fail to compile.
+
=== Bundle File Wrapper Factory Hook ===
  
−
==Standard Execution Environments==
+
=== Bundle Watcher Hook ===
−
The set of execution environments is extensible but the Eclipse IDE includes support for the environments set out in the OSGi R4 specification.  These are summarized in the table below.
+
  
−
{|
+
=== Class Loading Hook ===
−
!width="150"|EE Name
+
 
−
!width="500"|Description
+
=== Class Loading Stats Hook ===
−
|-
+
 
−
|'''OSGi/Minimum-1.0'''
+
=== Storage Hook ===
−
|OSGi Minimum Execution Environment 1.0 - This is a subset of the J2ME Foundation 1.0 class libraries defined by OSGi to be the base for framework implementations.
+
 
−
|-
+
== Bundle Files ==
−
|'''OSGi/Minimum-1.1'''
+
 
−
|OSGi Minimum Execution Environment 1.1 - This is a subset of the J2ME Foundation class libraries defined by OSGi to be the base for framework implementations.
+
== Class Loaders ==
−
|-
+
 
−
|'''CDC-1.0/Foundation-1.0'''
+
== Examples ==
−
|J2ME Foundation 1.0 - With the exception of some MicroEdition IO classes, Foundation 1.0 is a subset of J2SE 1.3.
+
−
|-
+
−
|'''CDC-1.1/Foundation-1.1'''
+
−
|J2ME Foundation 1.1 - With the exception of some MicroEdition IO classes, Foundation 1.1 is a subset of J2SE 1.4.
+
−
|-
+
−
|'''JRE-1.1'''
+
−
|-
+
−
|'''J2SE-1.2'''
+
−
|-
+
−
|'''J2SE-1.3'''
+
−
|-
+
−
|'''J2SE-1.4'''
+
−
|-
+
−
|'''J2SE-1.5'''
+
−
|-
+
−
|'''JavaSE-1.6'''
+
−
|}
+

Revision as of 11:48, 22 April 2006

Overview

Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi Framework. A framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasks. A framework adaptor may be used to add functionality to the framework.

A single framework adaptor is specified when the framework is launched. By default in Eclipse 3.0 this is set to the EclipseAdaptor. In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations. This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.

In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor. The framework adaptor API has remained unchanged for the most part in Eclipse 3.2. What has changed is the actual implementation of the adaptor API. A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.

Hookable Adaptor

The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor. This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework. It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundles. See the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.

Framework extension bundles are fragments of the system bundle (org.eclipse.osgi). As a fragment they can provide extra classes which the framework can use. A framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file).

The Base Adaptor

The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor. This class is used by default as the adaptor of the framework. You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.

In some cases it may be impossible to do what you want with the current set of adaptor hooks. In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementation. If you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.

The Hook Registry

The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework. When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry. The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.

Hook Configurators

Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interface. Hook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.

Discovering Hook Configurators

In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader. This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle. Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).

A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.

hookconfigurators.properties files

A hookconfigurators.properties file can be used to declare a list of hook configator classes. The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes. For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar: 

hook.configurators= 
   org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
   org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
   org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
   org.eclipse.core.runtime.internal.stats.StatsManager,
   org.eclipse.osgi.internal.verifier.SignedBundleHook

Quite a few hook configurators are automatically enabled by default withing the Equinox Framework. The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator. All other configurators declared above add extra functionality needed by eclipse and can be disabled.

Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators. The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.

osgi.hook.configurators property

The osgi.hook.configurators configuration property is used to specify the list of hook configurators. If this property is set then the list of configurators specified will be the only configurators used. If this property is set then the hookconfigurators.properties files will not be processed for additional configurators. This property can be used in a config.ini to lock down the set of configurators to a specific set.

osgi.hook.configurators.include property

The osgi.hook.configurators.include configuration property is used to add additional hook configurators. This is helpful for configuring optional hook configurators. Hooks that should be enabled by default should be included in a hookconfigurators.properties file. This property is ignored if the osgi.hook.configurators is set.

osgi.hook.configurators.exclude property

The osgi.hook.configurators.include configuration property is used to exclude any hook configurators. This is helpful for disabling hook configurators that are specified in hook configurator properties files. This property is ignored if the osgi.hook.configurators is set.

Hook interfaces

Adaptor Hook

Bundle File Factory Hook

Bundle File Wrapper Factory Hook

Bundle Watcher Hook

Class Loading Hook

Class Loading Stats Hook

Storage Hook

Bundle Files

Class Loaders

Examples

Retrieved from "https://wiki.eclipse.org/index.php?title=Execution_Environments&oldid=4220"

Back to the top