OtEquinox/ConfigIni

up: OtEquinox

This is an Archived Page

Please see the new version at Eclipse.org

OT-Specific Declarations in config.ini

The file configuration/config.ini contains fundamental settings for an OSGi installation. OT/Equinox adds a few additional declarations to this file, which are described here.

Mandatory declarations:

Adding mandatory declarations to the file config.ini is done through the "touchpoint" mechanism of the "p2" provisioning system, so everything happens automatically while installing the OTDT. This section only gives background for those who want to know what's going on behind the scenes. 

osgi.hook.configurators.include=org.objectteams.eclipse.transformer.hook.HookConfigurator
osgi.framework.extensions=org.objectteams.eclipse.transformer.hook

These two declarations announce the OT/J bytecode transformers to the OSGi framework, by using the hooks described in  http://wiki.eclipse.org/index.php/Adaptor_Hooks. 

osgi.classloader.lock=classname

This line is also recommended in order to tell the framework to use a new locking strategy for all classloaders, which is known to work best for OT/Equinox. Due to the top voted bug reported against the Sun JVM (see  https://bugs.eclipse.org/121737) additionally two vendor-specific options need to be passed to the JVM, which happens by the following entries in eclipse.ini (after -vmargs): 

-XX:+UnlockDiagnosticVMOptions
-XX:+UnsyncloadClass

ot.equinox=1

This simple flag is needed to tell the OTRE that it runs inside OSGi. 

osgi.splashPath=platform\:/base/plugins/org.objectteams.otdt

This declaration tells the launcher to show the splash screen which has been customized for the OTDT. Note, that also eclipse.ini contains a similar declaration, where precedence between both declarations is not perfectly clear.

Optional application specific declarations

Forced Exports

OT/Equinox supports the notion of forced exports by which roles can be bound to base classes from another bundle even if these base classes are not exported from their bundle. This specific form of decapsulation consists of two parts:

The only legal access to a force-exported class is via a playedBy binding.

This page describes how config.ini is used for granting forced exports for a given Eclipse installation.

Syntax:

(camel cased words are non-terminals, | denotes a choice, everything else on the RHS is literal) 

ForcedExportDecls     ::= otequinox.forced.exports=ForcedExports
ForcedExports         ::= ForcedExport | ForcedExport,ForcedExports
ForcedExport          ::= BaseBundleID[PackageExports]
PackageExports        ::= PackageExport | PackageExport,PackageExports
PackageExport         ::= PackageName;x-friends:=AspectBundleIDs
AspectBundleIDs       ::= AspectBundleID | "QuotedAspectBundleIDs"
QuotedAspectBundleIDs ::= AspectBundleID | AspectBundleID,QuotedAspectBundleIDs

Simple Example:

otequinox.forced.exports=some.base.bundle1[some.base.pack1;x-friends:="some.aspect1"]

Complex Example:

otequinox.forced.exports=some.base.bundle1[some.base.pack1;x-friends:="some.aspect1,some.aspect2",some.base.pack2;x-friends:=some.aspect1],some.base.bundle2[some.base.pack3;x-friends:=some.aspect3]

The declaration is used to tell the framework that a given package within a given base bundle (e.g., some.base.pack1 within bundle some.base.bundle) should be exported to one or more specific aspects (e.g., some.aspect1), although the base bundle does not declare to export the given package.
The PackageExports part actually utilizes the syntax from a Export-Package: directive within a bundle's MANIFEST.MF, but note, that the x-friend part is actually mandatory here.

In order for this declaration to be effective, also the aspect's plugin.xml must contain an AspectBinding with a matching forcedExports element (only a package/list of packages, without the base bundle ID nor the x-friends part). With matching declarations in both locations in place, the given aspect bundle may indeed access classes from the otherwise inaccessible base package. Such usage is in fact restricted to base imports and any uses that are allowed for base imported classes.

The complex example above shows that declarations can soon become lengthy, yet the declaration must be given on a single line within config.ini. Since version 1.2.6 it is possible to extract the forced exports declaration into a separate file and just leave a reference to this file within config.ini (see ticket #198). As mentioned, other levels for granting forced exports exist by way of OtEquinox/AspectBindingNegotiation.

Compilation vs. Runtime:

The above explains how forced exports are enabled in the OT/Equinox runtime. As of #18 the compiler also interprets the declarations from plugin.xml and checks them against usage within the code.

Whether or not the compiler should report forced exports can be configured by the "decapsulation" warning token, or "Decapsulation (overriding access restrictions)" when using the compiler preferences dialog -- choose one of error/warning/ignore. The compiler will never tolerate access to a non-exported base class for which no forced export is declared.

References: