2016/05/28 - Apache Tuscany has been retired.

<implementation.osgi>

Tuscany enables OSGi bundles to be used as the implementation of SCA components by using the <implementation.osgi/> SCDL extension. OSGi services registered in the OSGi service registry either using OSGi declarative services or  through the OSGi procedural services API can be exposed as services of the SCA component.

The OSGi component implementation SCDL has the following format:

<implementation.osgi
        bundleSymbolicName=""
        [bundleVersion=""]
        [classes=""]
        [imports=""]>
    <properties service="">...</properties>*
    <properties reference="">...</properties>*
    <properties serviceCallback="">...</properties>*
    <properties referenceCallback="">...</properties>*
</implementation.osgi>

The bundle is identified by its symbolic name, which is used to locate the bundle in the SCA contribution. The version of the bundle can be optionally specified if multiple versions of the bundle are present in the contribution.

The list of classes in the bundle which contain SCA annotations that should be processed by the SCA runtime can be specified in the classes attribute of <implementation.osgi/>. If this list is not provided, only the implementation classes of service instances will be scanned for SCA annotations. A list of dependent bundles can also be specified in the imports attribute. If provided, these bundles are installed and started before the implementation bundle.

OSGi services registered in the OSGi registry can have properties associated with the service registration. These properties can be used to lookup services in the registry. The properties of services, references and callbacks associated with OSGi services can be optionally specified. These will be used to create the filter for locating these services in the OSGi registry. 

A component type file should be provided for SCA components using an OSGi bundle as its implementation. This file should have the same base name and location as the bundle.

Example:

This example shows a simple composite with two components that use <implementation.osgi/>:

<composite xmlns=http://www.osoa.org/xmlns/sca/1.0
    targetNamespace=http://helloworld
    name="HelloWorld">

    <component name="HelloWorldClient">
        <implementation.osgi xmlns=http://tuscany.apache.org/xmlns/sca/1.0
             bundleSymbolicName="helloworld.HelloWorldClient"                   
             bundleVersion="1.0.0">
            <properties reference="helloWorldService">
                <property name="language">English</property>
            </properties>
        </implementation.osgi>
        <reference name="helloWorldService" target="HelloWorldService"/>
   </component>
   <component name="HelloWorldService">
        <implementation.osgi xmlns=http://tuscany.apache.org/xmlns/sca/1.0
             bundleSymbolicName="helloworld.HelloWorldService"                         
             bundleVersion="1.0.0">
            <properties service="HelloWorldService">
                <property name="language">English</property>
            </properties>
        </implementation.osgi>
      </component>
</composite>

This example shows two components which use OSGi implementation. Each component implementation is an OSGi bundle, and one of the services from each bundle is exposed through SCA. The bundles are identified using their symbolic name and version which are values of the manifest attributes Bundle-SymbolicName and Bundle-Version respectively in the bundle jar files. The bundle jar files can either be a contribution in the SCA domain, or contained in a contribution in the SCA domain.

The properties specified for the reference of HelloWorldClient are used to lookup HelloWorldService in the OSGi registry. These properties should match the properties specified for the service of HelloWorldService. 

The OSGi bundles should register the services exposed through SCA when the bundle is activated. Services are registered using standard OSGi service registration mechanism. References should be looked up in the OSGi service registry using registry lookup. SCA runtime does not perform reference injection for OSGi-based component implementation. Reference lookup should always use the service registered with the highest ranking to ensure that SCA wiring and scope are maintained. When OSGi declarative services are used, service registration and reference binding are performed by the OSGi declarative services runtime. References from components using <implementation.osgi/> can be wired to non-OSGi services, and non-OSGi components can access OSGi services. For example, either of the two components in this example can use <implementation.java/> as their implementation.

Default scope for OSGi-based components is COMPOSITE. For scopes other than composite scope, a service factory should be registered in the OSGi service registry. Service factories should also be used for OSGi services which are used in multiple SCA components with different component properties.