[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[equinox-dev] Deprecation of version-match attribute


This note only concerns developers of plugins that have hand crafted bundle manifest files (META-INF/MANIFEST.MF) and that use the Require-Bundle and Fragment-Host manifest headers.  If you do not do any of these things you can ignore this note.

The version-match attribute for the Require-Bundle and Fragment-Host manifest headers has been deprecated.  The version-match attribute allowed developers to specify match rules when declaring required bundles and fragment hosts.  There was a predefined set of match rules that the Framework understood (qualifier, micro, minor, major, greaterthan-or-equal).  This allowed developers to specify what versions they were willing to accept for use within their bundle/plugin

The OSGi community felt that the predefined set of match rules was limiting because it did not allow you to specify an arbitrary range of versions to match against.  For example, the following Require-Bundle header specifies that a bundle requires org.eclipse.foo

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0; version-match=major

The version-match=major specifies that any plugin org.eclipse.foo with a major version number equal to 3 is acceptable (e.g 3.0.1, 3.1.0, ... but not 4.0).  While this model satisfies most developers it does not allow for more complex range checks.  For example match on versions 3.0.2 to 4.5.1.  The OSGi community has decided to remove the version-match attribute and enhance the syntax to the bundle-version attribute.  The new syntax for bundle-version will allow a developer to specify a range of versions to match against using the mathematical floor and ceiling notation.

Here are some examples of the new syntax the first line uses the old version-match attribute and the following line uses the new version range syntax:

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0.test; version-match=qualifier
Require-Bundle: org.eclipse.foo; bundle-version="[3.0.0.test,3.0.0.test]"

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0; version-match=micro
Require-Bundle: org.eclipse.foo; bundle-version="[3.0.0,3.0.1)"

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0; version-match=minor
Require-Bundle: org.eclipse.foo; bundle-version="[3.0.0,3.1.0)"

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0; version-match=major
Require-Bundle: org.eclipse.foo; bundle-version="[3.0.0,4.0.0)"

Require-Bundle: org.eclipse.foo; bundle-version=3.0.0; version-match=greaterthan-or-equal
Require-Bundle: org.eclipse.foo; bundle-version=3.0.0


The general syntax for bundle-version is:
        [ floor , ceiling )

Where floor is the minimum version and ceiling is the maximum version to match against.  The first character may be '[' or '('.  The character '[' indicates that the floor is included in the range and '(' indicates the floor is NOT included in the range.  The last character may be ']' or ')'.  The character ']' indicates that the ceiling is included in the range and ')' indicates that the ceiling is NOT included in the range.  If you want to specify greaterthan-or-equal then you only specify the version with no extra characters.  When specifying a version range you MUST use a quoted string like the examples above.

This change should only effect a limited group of developers that are using hand crafted bundle manifest files and use the bundle-version or version-match attributes.  The only eclipse component that have such manifests is SWT.  I will open a bug report against SWT and supply a patch for them to update their manifest files.

Thomas Watson