[equinox-dev] Deprecation of version-match attribute

[Thomas Watson <tjwatson@xxxxxxxxxx>]

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