[
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
