What are Execution Environments?
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.
Execution environments are relevant both to development (compile) time and runtime.
So what does this mean to me and my bundles?
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.
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!
Wow! Is this hard to setup?
Not really. OSGi allows bundles to be marked with the minimum execution environment they require (see the information below). 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?
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 of course specify that EE. Remember however that people running on J2SE-1.4, Foundation 1.*, etc. will then not be able to use your bundle.
Projects should not leave these choices to chance. For example, the Eclipse Project has explicitly identified EEs for all of their bundles. These choices are documented in the 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.
Setting the Execution Environment
- Use build N20060420-0010 or later.
- Right click on your plug-in's MANIFEST.MF 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).
- 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.
Managing Execution Environments
Foundation Class Libraries
Plug-ins that are 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. Listing them both will in essence say that the intersection of the two is valid for use in that plug-in. The situation is the same for Foundation 1.1 and J2SE-1.4.
Getting J9 is the easiest way to get a Foundation JRE to run or compile against.
Compiling Against More Than Is Required
In some cases, a plug-in may require a higher version to compile against, but is able to run perfectly fine against a lower version. For instance, the org.eclipse.osgi bundle will use java.nio.* classes if available. So it must be compiled against J2SE-1.4 but can run on OSGI/Minimum-1.0.
In these cases the EE required to compile against must appear first in the list. So for org.eclipse.osgi, the list (in order) is J2SE-1.4 then OSGI/Minimum-1.0.
Some bundles may think that they require an EE of J2SE-1.4 but really the only special thing that they require from the 1.4 class libraries are the JAXP XML APIs. So in these cases they can be listed as having an EE of J2SE-1.3 because they still will run ok if another bundle is providing the XML APIs.