You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by "Rupert Westenthaler (JIRA)" <ji...@apache.org> on 2012/10/13 12:19:02 UTC
[jira] [Created] (STANBOL-774) Stanbol Bundels that export packages
containing service interfaces or classes that are referenced in service
interfaces need also import those packages
Rupert Westenthaler created STANBOL-774:
-------------------------------------------
Summary: Stanbol Bundels that export packages containing service interfaces or classes that are referenced in service interfaces need also import those packages
Key: STANBOL-774
URL: https://issues.apache.org/jira/browse/STANBOL-774
Project: Stanbol
Issue Type: Sub-task
Reporter: Rupert Westenthaler
Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
[1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
[2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (STANBOL-774) Check Exported, Imported and
Private Packages; use version ranges for Imports
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13478757#comment-13478757 ]
Rupert Westenthaler commented on STANBOL-774:
---------------------------------------------
The best Practice for Versioning [2] includes
> If you provide an API (as defined in te Semantic Versioning
> whitepaper) export the API package even if it is not in your
> project and put the provide:=true directive on the package
I have not followed this suggestion for now, mainly because it looked strange to me if 10+ EnhancementEngines do export the o.a.s.enhancer.servicesapi package.
Maybe we should change that. Any opinnion?
> Check Exported, Imported and Private Packages; use version ranges for Imports
> -----------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> To use Apache Stanbol in such a scenario one must be more careful with OSGI metadata in the Stanbol bundle manifests.
> This Issue covers mainly two improvements:
> 1. Ensure that all exported (and internally used) packages are also imported. Otherwise internal usage of non-imported packages would case incompatibilities with the host application as it could not cast instances created by using the internal Classes to the Classes loaded by the Host applications Classloader (see [2] for details).
> 2. Ensure that Stanbol bundles use proper version ranges for imported packages. The Host Application is limited to a single version of a Class. So if different Stanbol Bundles do require different versions of a module those can not be correctly exposed form the Host Application via the System Bundle - what would make it impossible for a Host Application to use the affected Stanbol Modules together. To avoid it is important do not import fixed version but rather to use proper version ranges for imported packages.
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Comment Edited] (STANBOL-774) Stanbol Bundels that export
packages containing service interfaces or classes that are referenced in
service interfaces need also import those packages
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13475622#comment-13475622 ]
Rupert Westenthaler edited comment on STANBOL-774 at 10/13/12 3:34 PM:
-----------------------------------------------------------------------
from the Bnd Tool documentation (http://www.aqute.biz/Bnd/Versioning)
## Substitution
> After the bundle has been created and analyzed bnd will see if an exported package is eligible for import.
> An export is automatically imported when the following are true:
>
> * There exists at least one reference to the exported package from a private package
> * The exported package has no references to any private packages
> * The exported package does not have a -noimport: directive.
>
> If a package is imported it will use the version as defined by the version policy.
## Import Version Policy
> If you import a package bnd will look at the exported version of that package.
> This version is not directly suitable for the import because it is usually too specific,
> it needs a policy to convert this export version to an import version.
Two policies
> -provider-policy : ${range;[==,=+)}
> -consumer-policy : ${range;[==,+)}
consumer-policy is the default and is fine for all cases except
> If you provide an API (as defined in te Semantic Versioning whitepaper) export the API package
> even if it is not in your project and put the provide:=true directive on the package export,
> e.g. Export-Package: org.osgi.service.event; provide:=true.
was (Author: rwesten):
from the Bnd Tool documentation (http://www.aqute.biz/Bnd/Versioning)
## Substitution
> After the bundle has been created and analyzed bnd will see if an exported package is eligible for import.
> An export is automatically imported when the following are true:
>
> * There exists at least one reference to the exported package from a private package
> * The exported package has no references to any private packages
> * The exported package does not have a -noimport: directive.
>
> If a package is imported it will use the version as defined by the version policy.
## Import Version Policy
> If you import a package bnd will look at the exported version of that package.
> This version is not directly suitable for the import because it is usually too specific,
> it needs a policy to convert this export version to an import version.
Two policies
> -provider-policy : ${range;[==,=+)}
> -consumer-policy : ${range;[==,+)}
consumer-policy is the default and should be used for everything other than packages containing Interfaces the current module/bundle actually implements.
> Stanbol Bundels that export packages containing service interfaces or classes that are referenced in service interfaces need also import those packages
> -------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (STANBOL-774) Check Exported, Imported and
Private Packages; use version ranges for Imports
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13477708#comment-13477708 ]
Rupert Westenthaler commented on STANBOL-774:
---------------------------------------------
## Correctly applying "-provider-policy"
As stated above it is important to use the "-provider-policy" for packages that define interfaces (or abstract classes) an Module implements themself. The following section does provides examples of such cases.
### Module that provides an implementation of the imported interface
The most common Example of such a Scenario are EnhancementEngines. So I will use this for the example.
Enhancement Engines implement an Interface defined in "org.apache.stanbol.enhancer.servicesapi" and typically also extend the abstract super class defined in "org.apache.stanbol.enhancer.servicesapi.impl".
Because of that implementors of an EnhancementEngine want to use the "-provider-policy" for those two packages. As the default is the "-consumer-policy" an according configuration need to be set for both packages in the instruction section of the "maven-bundle-plugin" in the modules pom.xml file.
<instructions>
<Import-Package>
org.apache.stanbol.enhancer.servicesapi; provide:=true,
org.apache.stanbol.enhancer.servicesapi.impl; provide:=true,
*
</Import-Package>
This configuration will generate the following Import-Package: statements
org.apache.stanbol.enhancer.servicesapi;version="[0.10.0,0.11)",
org.apache.stanbol.enhancer.servicesapi.helper;version="[0.10.0,1)",
org.apache.stanbol.enhancer.servicesapi.impl;version="[0.10.0,0.11)"
Note that the "-provider-policy" - "[0.10.0,0.11)" - is used for the servicesapi and servicesapi.impl package while the "-consumer-policy" - ""[0.10.0,1)" - is applied to the servicesapi.helper package.
### Exported Interfaces with Private implementation within the same module
If an Module defines an Interface but also includes an implementation for the same, that one needs also to ensure that the package that defines the same interface is exported by using the "-provider-policy".
There are not so much examples of that in Stanbol right now, but some of the EnhancementEngines currently developed in the branch for the NLP processing module do fall in that category.
The following Example uses the "EntitySearcher" interface defined by the KeywordLinkingEngine module in the "org.apache.stanbol.enhancer.engines.keywordextraction.linking". Private implementations of that interfaces are provided in "org.apache.stanbol.enhancer.engines.keywordextraction.linking.impl".
<Export-Package>
org.apache.stanbol.enhancer.engines.keywordextraction.impl;version=${project.version},
org.apache.stanbol.enhancer.engines.keywordextraction.engine;version=${project.version},
org.apache.stanbol.enhancer.engines.keywordextraction.linking;version=${project.version}; provide:=true,
</Export-Package>
<Private-Package>
org.apache.stanbol.enhancer.engines.keywordextraction.linking.impl
</Private-Package>
NOTE the "provided:=ture" parameter for the exported linking package with internal private implementations. This ensures that
Import-Package:
org.apache.stanbol.enhancer.engines.keywordextraction.linking;version="[0.10.0,0.11)"
and therefore that an imported version of that interface does not conflict with the provided implementation of the same.
However also note that packages will only appear in the "Import-Package" section if the following requirements are fulfilled.
> * There exists at least one reference to the exported package from a private package
> * The exported package has no references to any private packages
> * The exported package does not have a -noimport: directive.
So if the expected input is missing it is most likely because of incorrect dependencies of classes within the same package. So developers SHOULD check the generated MANIFEST.MF files!
> Check Exported, Imported and Private Packages; use version ranges for Imports
> -----------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> To use Apache Stanbol in such a scenario one must be more careful with OSGI metadata in the Stanbol bundle manifests.
> This Issue covers mainly two improvements:
> 1. Ensure that all exported (and internally used) packages are also imported. Otherwise internal usage of non-imported packages would case incompatibilities with the host application as it could not cast instances created by using the internal Classes to the Classes loaded by the Host applications Classloader (see [2] for details).
> 2. Ensure that Stanbol bundles use proper version ranges for imported packages. The Host Application is limited to a single version of a Class. So if different Stanbol Bundles do require different versions of a module those can not be correctly exposed form the Host Application via the System Bundle - what would make it impossible for a Host Application to use the affected Stanbol Modules together. To avoid it is important do not import fixed version but rather to use proper version ranges for imported packages.
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (STANBOL-774) Check Exported, Imported and Private
Packages; use version ranges for Imports
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rupert Westenthaler updated STANBOL-774:
----------------------------------------
Summary: Check Exported, Imported and Private Packages; use version ranges for Imports (was: Stanbol Bundels that export packages containing service interfaces or classes that are referenced in service interfaces need also import those packages)
> Check Exported, Imported and Private Packages; use version ranges for Imports
> -----------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (STANBOL-774) Check Exported, Imported and Private
Packages; use version ranges for Imports
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rupert Westenthaler updated STANBOL-774:
----------------------------------------
Description:
Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
To use Apache Stanbol in such a scenario one must be more careful with OSGI metadata in the Stanbol bundle manifests.
This Issue covers mainly two improvements:
1. Ensure that all exported (and internally used) packages are also imported. Otherwise internal usage of non-imported packages would case incompatibilities with the host application as it could not cast instances created by using the internal Classes to the Classes loaded by the Host applications Classloader (see [2] for details).
2. Ensure that Stanbol bundles use proper version ranges for imported packages. The Host Application is limited to a single version of a Class. So if different Stanbol Bundles do require different versions of a module those can not be correctly exposed form the Host Application via the System Bundle - what would make it impossible for a Host Application to use the affected Stanbol Modules together. To avoid it is important do not import fixed version but rather to use proper version ranges for imported packages.
[1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
[2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
was:
Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
[1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
[2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
> Check Exported, Imported and Private Packages; use version ranges for Imports
> -----------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> To use Apache Stanbol in such a scenario one must be more careful with OSGI metadata in the Stanbol bundle manifests.
> This Issue covers mainly two improvements:
> 1. Ensure that all exported (and internally used) packages are also imported. Otherwise internal usage of non-imported packages would case incompatibilities with the host application as it could not cast instances created by using the internal Classes to the Classes loaded by the Host applications Classloader (see [2] for details).
> 2. Ensure that Stanbol bundles use proper version ranges for imported packages. The Host Application is limited to a single version of a Class. So if different Stanbol Bundles do require different versions of a module those can not be correctly exposed form the Host Application via the System Bundle - what would make it impossible for a Host Application to use the affected Stanbol Modules together. To avoid it is important do not import fixed version but rather to use proper version ranges for imported packages.
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (STANBOL-774) Stanbol Bundels that export
packages containing service interfaces or classes that are referenced in
service interfaces need also import those packages
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13475661#comment-13475661 ]
Rupert Westenthaler commented on STANBOL-774:
---------------------------------------------
using the "-provider-policy" and "-consumer-policy" as described would require to add the following instructions for the configuration of the "maven-bundle-plugin" in the parent POM.
<_provider-policy>[$(version;===;$(@)),$(version;=+;$(@)))</_provider-policy>
<_consumer-policy>[$(version;===;$(@)),$(version;+;$(@)))</_consumer-policy>
> Stanbol Bundels that export packages containing service interfaces or classes that are referenced in service interfaces need also import those packages
> -------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (STANBOL-774) Stanbol Bundels that export
packages containing service interfaces or classes that are referenced in
service interfaces need also import those packages
Posted by "Rupert Westenthaler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/STANBOL-774?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13475622#comment-13475622 ]
Rupert Westenthaler commented on STANBOL-774:
---------------------------------------------
from the Bnd Tool documentation (http://www.aqute.biz/Bnd/Versioning)
## Substitution
> After the bundle has been created and analyzed bnd will see if an exported package is eligible for import.
> An export is automatically imported when the following are true:
>
> * There exists at least one reference to the exported package from a private package
> * The exported package has no references to any private packages
> * The exported package does not have a -noimport: directive.
>
> If a package is imported it will use the version as defined by the version policy.
## Import Version Policy
> If you import a package bnd will look at the exported version of that package.
> This version is not directly suitable for the import because it is usually too specific,
> it needs a policy to convert this export version to an import version.
Two policies
> -provider-policy : ${range;[==,=+)}
> -consumer-policy : ${range;[==,+)}
consumer-policy is the default and should be used for everything other than packages containing Interfaces the current module/bundle actually implements.
> Stanbol Bundels that export packages containing service interfaces or classes that are referenced in service interfaces need also import those packages
> -------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: STANBOL-774
> URL: https://issues.apache.org/jira/browse/STANBOL-774
> Project: Stanbol
> Issue Type: Sub-task
> Reporter: Rupert Westenthaler
>
> Host Applications that do run Stanbol in an embedded OSGI environment need to export all packages of used Interfaces (and all Classes used in those Interfaces). This is required to ensure that the java Classes used by Stanbol (running within the embedded OSGI environment) are the same as the one available to the Host application (see [1] for details).
> However Bundles that do not explicitly import packages they export will rather user their internal version instead of the version exported by the Host application causing the Class version to become incompatible (see [2] for details).
> [1] http://felix.apache.org/site/apache-felix-framework-launching-and-embedding.html#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage
> [2] http://felix.apache.org/site/apache-felix-osgi-faq.html#ApacheFelixOSGiFAQ-Shouldabundleimportitsownexportedpackages?
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira