[jira] [Commented] (STANBOL-774) Check Exported, Imported and Private Packages; use version ranges for Imports

["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