felix "missing requirement" if bundle imports own API

[shadogray]

After reading some postings on the topic exports-to-imports I understood, that it is considered "good practice" of an api-bundle to import its own API to enable single source resolution if more than one bundle exports this same API.

Now I wanted to use bundle commons-cli from apache and got this exception:

ERROR: Bundle org.apache.commons.cli [12] Error starting file:/work/java/osgi/felix/bundle/commons-cli-1.2.jar (org.osgi.framework.BundleException: Unresolved constraint in bundle org.apache.commons.cli [12]: Unable to resolve 12.0: missing requirement [12.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.commons.cli)(version>=1.2.0)))

The bundle looks like this:
~> bnd print commons-cli-1.2.jar
[MANIFEST commons-cli-1.2]
Bundle-Name                              Commons CLI                            
Bundle-SymbolicName                      org.apache.commons.cli                 
Bundle-Vendor                            The Apache Software Foundation         
Bundle-Version                           1.2                                    
Export-Package                           org.apache.commons.cli                 
Implementation-Version                   1.2                                    
Import-Package                           org.apache.commons.cli;version="1.2"   

[IMPEXP]
Import-Package
  org.apache.commons.cli                 {version=1.2}
Export-Package
  org.apache.commons.cli                 {imported-as=1.2}

Can you please explain what this means?
Regards,
Thomas

[Neil Bartlett]

There is a version mismatch. You're importing the package as version 1.2 but exporting as version 0.0.0.

Regards,
Neil

[shadogray]

Many thanks for the explanation, this means that the Bundle-Version is not automatically used during resolution?
I find reading the spec 4.2 that there are two relevant predefined attributes: "version" and "bundle-version".
And further:
"The Framework will automatically associate each package export definition with the following attributes:
• bundle-symbolic-name – The bundle symbolic name of the exporting bundle. In the case of a fragment bundle, this is the host bundle’s symbolic name.
• bundle-version – The bundle version of the exporting bundle. In the case of a fragment bundle, this is the host bundle’s version."

Does that mean, that in fact the mentioned bundle export should be read something like:
Export-Package: org.apache.commons.cli; bundle-version="1.2"

and not as I expected:
Export-Package: org.apache.commons.cli; version="1.2"

This even though the bundle also defines the Specification-Version: 1.2, which should be regarded an alias to the "version" attribute?

Do I understand correctly, that the importing version constraint attribute can _only_ be satisfied, if the exporting bundle _explicitly_ adds a matching version attribute to the Export-Package statement?

Please clarify,
Thomas

[Neil Bartlett]

Responses inline below.

shadogray wrote:

Many thanks for the explanation, this means that the Bundle-Version is
not automatically used during resolution?

Bundle-Version is only used when the importing bundle uses Require-Bundle instead of Import-Package. Since using Require-Bundle is essentially deprecated, this means that in the majority of cases, Bundle-Version is indeed NOT used during resolution.

I find reading the spec 4.2 that there are two relevant predefined
attributes: "version" and "bundle-version".
And further:
"The Framework will automatically associate each package export
definition with the following attributes:
• bundle-symbolic-name – The bundle symbolic name of the exporting
bundle. In the case of a fragment bundle, this is the host bundle’s
symbolic name.
• bundle-version – The bundle version of the exporting bundle. In the
case of a fragment bundle, this is the host bundle’s version."

Does that mean, that in fact the mentioned bundle export should be
read something like:
Export-Package: org.apache.commons.cli; bundle-version="1.2"

No this is incorrect; the bundle-version attribute is meaningless on an export.

and not as I expected:
Export-Package: org.apache.commons.cli; version="1.2"

This is the correct way to specify the version of an export.

This even though the bundle also defines the Specification-Version:
1.2, which should be regarded an alias to the "version" attribute?

"Specification-Version" is not an OSGi header, and will be ignored. It is not an alias for anything.

Do I understand correctly, that the importing version constraint
attribute can _only_ be satisfied, if the exporting bundle
_explicitly_ adds a matching version attribute to the Export-Package
statement?

Yes you should always version your exports.

However you should NOT have to explicitly write the Import-Package statement corresponding to those exports: bnd will generate that for you, with the correct version range, if it is required.

[shadogray]

To me it seems unfortunate, that so many header attributes seem to have no relevance in the end?

You said:

"Specification-Version" is not an OSGi header, and will be ignored. It is not an alias for anything.
 

but spec 4.2 explicitly names it:

6.1.13.68 public static final String PACKAGE_SPECIFICATION_VERSION = “specification-version”
Manifest header attribute identifying the version of a package specified in the Export-Package or Import-Package manifest header. As of 1.3. This has been replaced by VERSION_ATTRIBUTE.
 

However you should NOT have to explicitly write the Import-Package statement corresponding to those exports: bnd will generate that for you, with the correct version range, if it is required.

I tried to follow your advice and use bnd wrap to generate version ranges on exports and imports automatically.
Unfortunately all generated exports are versionless.
Do I have to specify a certain attribute in the properties file to make bnd wrap add these version ranges?
After reading the code I find the part of export/import management quite evolved :-)

Many thanks again for your help,
Thomas

[Peter Kriens]

- Yes, specification-version was the original name of the version attribute ... It basically is deprecated.

- bnd wrap is for quick use, for serious use, always make a bnd file that controls the process. In this

  process you can easily apply versions. For example:

    myjar.bnd:

Include-Resource: jar/myjar-1.0.jar

-exportcontents: com.example.abc; version=1.9

Bundle-Description: This is a wrapped version of ...

Bundle-Copyright: ...

Bundle-License: ...

I would make a project where you maintain these files. bnd can make them all in one go (I think): bnd *.bnd

This way. when there is an update of the jar, you can easily generate the next version. You can then even use the bnd release process to ensure you do not violate any of the semantic versioning rules.

Kind regards,

Peter Kriens

[shadogray]

Thank you for clarification, this made it definitely clear, which way to go :-)
Best regards,
Thomas

[Neil Bartlett]

I didn't even know that Specification-Version was an old OSGi header... you learn something every day ;-)

Neil

Peter Kriens

9 October 2012 07:38

- Yes, specification-version was the original name of the version attribute ... It basically is deprecated.

- bnd wrap is for quick use, for serious use, always make a bnd file that controls the process. In this

  process you can easily apply versions. For example:

    myjar.bnd:

Include-Resource: jar/myjar-1.0.jar

-exportcontents: com.example.abc; version=1.9

Bundle-Description: This is a wrapped version of ...

Bundle-Copyright: ...

Bundle-License: ...

I would make a project where you maintain these files. bnd can make them all in one go (I think): bnd *.bnd

This way. when there is an update of the jar, you can easily generate the next version. You can then even use the bnd release process to ensure you do not violate any of the semantic versioning rules.

Kind regards,

Peter Kriens

shadogray

9 October 2012 00:02

To me it seems unfortunate, that so many header attributes seem to have no relevance in the end?
You said:

"Specification-Version" is not an OSGi header, and will be ignored. It is not an alias for anything.
 

but spec 4.2 explicitly names it:

6.1.13.68 public static final String PACKAGE_SPECIFICATION_VERSION = “specification-version”
Manifest header attribute identifying the version of a package specified in the Export-Package or Import-Package manifest header. As of 1.3. This has been replaced by VERSION_ATTRIBUTE.
 

However you should NOT have to explicitly write the Import-Package statement corresponding to those exports: bnd will generate that for you, with the correct version range, if it is required.

I tried to follow your advice and use bnd wrap to generate version ranges on exports and imports automatically.
Unfortunately all generated exports are versionless.
Do I have to specify a certain attribute in the properties file to make bnd wrap add these version ranges?
After reading the code I find the part of export/import management quite evolved :-)

Many thanks again for your help,
Thomas

Neil Bartlett

8 October 2012 09:20

Responses inline below.

shadogray wrote:

Many thanks for the explanation, this means that the Bundle-Version is
not automatically used during resolution?

Bundle-Version is only used when the importing bundle uses Require-Bundle instead of Import-Package. Since using Require-Bundle is essentially deprecated, this means that in the majority of cases, Bundle-Version is indeed NOT used during resolution.

I find reading the spec 4.2 that there are two relevant predefined
attributes: "version" and "bundle-version".
And further:
"The Framework will automatically associate each package export
definition with the following attributes:
• bundle-symbolic-name – The bundle symbolic name of the exporting
bundle. In the case of a fragment bundle, this is the host bundle’s
symbolic name.
• bundle-version – The bundle version of the exporting bundle. In the
case of a fragment bundle, this is the host bundle’s version."

Does that mean, that in fact the mentioned bundle export should be
read something like:
Export-Package: org.apache.commons.cli; bundle-version="1.2"

No this is incorrect; the bundle-version attribute is meaningless on an export.

and not as I expected:
Export-Package: org.apache.commons.cli; version="1.2"

This is the correct way to specify the version of an export.

This even though the bundle also defines the Specification-Version:
1.2, which should be regarded an alias to the "version" attribute?

"Specification-Version" is not an OSGi header, and will be ignored. It is not an alias for anything.

Do I understand correctly, that the importing version constraint
attribute can _only_ be satisfied, if the exporting bundle
_explicitly_ adds a matching version attribute to the Export-Package
statement?

Yes you should always version your exports.

However you should NOT have to explicitly write the Import-Package statement corresponding to those exports: bnd will generate that for you, with the correct version range, if it is required.

Please clarify,
Thomas

Am Montag, 8. Oktober 2012 08:13:01 UTC+2 schrieb Neil Bartlett:

    There is a version mismatch. You're importing the package as
    version 1.2 but exporting as version 0.0.0.

shadogray

8 October 2012 09:00

Many thanks for the explanation, this means that the Bundle-Version is not automatically used during resolution?

I find reading the spec 4.2 that there are two relevant predefined attributes: "version" and "bundle-version".
And further:
"The Framework will automatically associate each package export definition with the following attributes:
• bundle-symbolic-name – The bundle symbolic name of the exporting bundle. In the case of a fragment bundle, this is the host bundle’s symbolic name.
• bundle-version – The bundle version of the exporting bundle. In the case of a fragment bundle, this is the host bundle’s version."

Does that mean, that in fact the mentioned bundle export should be read something like:
Export-Package: org.apache.commons.cli; bundle-version="1.2"

and not as I expected:
Export-Package: org.apache.commons.cli; version="1.2"

This even though the bundle also defines the Specification-Version: 1.2, which should be regarded an alias to the "version" attribute?

Do I understand correctly, that the importing version constraint attribute can _only_ be satisfied, if the exporting bundle _explicitly_ adds a matching version attribute to the Export-Package statement?

Please clarify,
Thomas

Am Montag, 8. Oktober 2012 08:13:01 UTC+2 schrieb Neil Bartlett:

Neil Bartlett

8 October 2012 07:12

There is a version mismatch. You're importing the package as version 1.2 but exporting as version 0.0.0.

Regards,
Neil

shadogray wrote:

[BJ Hargrave]

On Oct 9, 2012, at 04:44 , Neil Bartlett <njbar...@gmail.com> wrote:

I didn't even know that Specification-Version was an old OSGi header... you learn something every day ;-)

It is not an old header. "specification-version" is an old attribute on the Export-Package and Import-Package headers which was deprecated and replaced by the version attribute.

-- 

BJ

[Matt Sayar]

For those joining this conversation late for some reason, note that you don't need to wrap commons-cli-1.2.jar. If you look at its manifest, it's already got all the proper OSGi information. My jar's manifest only looks like OPs after I tried wrapping it.