+

Search Tips   |   Advanced Search

Create a service bundle

For the simple HelloWorld OSGi application, the service bundle implements the HelloWorldEBA interface, and exports it as an OSGi service.

A bundle, the modular unit in the OSGi model, is a JAR file that includes the OSGi application metadata. This metadata is defined in the manifest file of the JAR file, META-INF/MANIFEST.MF.

  • Rational Application Developer v8.5 provides graphical support for creating and packaging bundles. The sample procedure that follows uses this tool. You can also use other tools, and the steps are adaptable to other tools.

    This sample procedure builds the following two bundles.

    • com.ibm.ws.eba.helloWorld.api: this bundle declares the HelloWorldEBA interface.

    • com.ibm.ws.eba.helloWorld.service: this bundle implements the HelloWorldEBA interface, and exports it as an OSGi service. The exported service is used by client bundle com.ibm.ws.eba.helloWorld.client, as described in Create a client bundle.

  • Demonstration of this task (9 min)

    To create the service bundle...

    1. Create the com.ibm.ws.eba.helloWorld.api bundle. This bundle declares the HelloWorldEBA interface.

      1. Click File > New > OSGi Bundle Project. The OSGi Bundle Project panel is displayed.

      2. Configure the project.

        • For the Project name, enter com.ibm.ws.eba.helloWorld.api.

        • Clear the Add bundle to application check box. If we leave this check box selected, a new OSGi application project is created automatically, and the bundle is added to it. Here, however, the application project will be created manually in a separate task, Create an OSGi application.

        • Leave the other options as the default values.

      3. Click Next. The Java Configuration panel is displayed. Accept the default values for all the options on this panel.

      4. Click Next. The OSGi bundle settings panel is displayed. Accept the default values for all the options on this panel.

      5. Click Finish.
      You have created the OSGi project.

    2. Declare the HelloWorldEBA interface.

      Create a package called com.ibm.ws.eba.helloWorld.api, that includes an interface called HelloWorldEBA. Code this interface to contain just one method: hello().

      1. Under the com.ibm.ws.eba.helloWorld.api project, right-click the folder src, then select New > Package.

      2. Name the new package com.ibm.ws.eba.helloWorld.api.

      3. Click Finish.

      4. Right-click the new package, then select New > Interface.

      5. Name the new interface HelloWorldEBA.

      6. Click Finish.

      7. Copy and paste the following method to replace the content of the interface file: 
        package com.ibm.ws.eba.helloWorld.api;
public interface HelloWorldEBA {

    public void hello();
}

      8. Save and close the file.

    3. Configure the com.ibm.ws.eba.helloWorld.api package as an exported package.

      Edit the bundle manifest in the com.ibm.ws.eba.helloWorld.api project to allow other bundles to load classes from the com.ibm.ws.eba.helloWorld.api package. Classes that are in packages not exported in the bundle manifest are private to the defining bundle and cannot be loaded by any other bundle.

      1. Open the bundle MANIFEST.MF file with the manifest editor. This file is in the BundleContent/META-INF directory.

      2. Click the Runtime tab.

      3. In the Exported Packages pane, click Add.

      4. Select the com.ibm.ws.eba.helloWorld.api package from the list, then click OK.

      5. In the Exported Packages pane, click Properties.

      6. In the Properties dialog, set the version to 1.0.0, then click OK.

      7. Save and close the file.

    4. Create the com.ibm.ws.eba.helloWorld.service bundle. This bundle implements the HelloWorldEBA interface.

      1. Click File > New > OSGi Bundle Project. The OSGi Bundle Project panel is displayed.

      2. Configure the project.

        • For the Project name, enter com.ibm.ws.eba.helloWorld.service.

        • Clear the Add bundle to application check box. If we leave this check box selected, a new OSGi application project is created automatically, and the bundle is added to it. Here, however, the application project will be created manually in a separate task, Create an OSGi application.

        • Leave the other options as the default values.

      3. Click Next. The Java Configuration panel is displayed. Accept the default values for all the options on this panel.

      4. Click Next. The OSGi bundle settings panel is displayed. Accept the default values for all the options on this panel.

      5. Click Finish.

    5. Make the HelloWorldEBA interface available to the service implementation bundle.

      Edit the client bundle manifest to make classes inside the com.ibm.ws.eba.helloWorld.api package available to the service implementation bundle. The com.ibm.ws.eba.helloWorld.api package is part of the com.ibm.ws.eba.helloWorld.api bundle.

      1. Expand the com.ibm.ws.eba.helloWorld.service project.

      2. Open the bundle MANIFEST.MF file with the manifest editor. This file is in the BundleContent/META-INF directory.

      3. Click the Dependencies tab.

      4. In the Imported Packages pane, click Add.

      5. In the Package Selection dialog, enter com.ibm.ws.eba, select com.ibm.ws.eba.helloWorld.api from the Exported Packages list, then click OK. The package is added to the Imported Packages list.

      6. In the Imported Packages list, select the com.ibm.ws.eba.helloWorld.api package then click Properties.

      7. In the Properties dialog, set the minimum version to 1.0.0 Inclusive, and set the maximum version to 1.1.0 Exclusive, then click OK. The entry for this package in the Imported Packages list is updated to com.ibm.ws.eba.helloWorld.api [1.0.0,1.1.0).

        This version syntax means "exported packages with versions between 1.0.0 inclusive and 1.1.0 exclusive will match this import". For more information on the version syntax, see section 3.2.6 "Version Ranges" of the OSGi Service Platform Release 4 Version 4.2 Core Specification.

        This version range has been specified to ensure that the implementation bundle uses an updated version of the package only if it differs in the value of the micro version, because a major change, such as removing a method from an interface, or a minor change, such as adding a method to an interface, could cause the implementation bundle to cease functioning correctly.

      8. Save and close the file.

    6. Implement the HelloWorld service.

      Create a package called com.ibm.ws.eba.helloWorld.service, that includes an implementation class called HelloWorldService. Code this class to implement the hello() method from the HelloWorldEBA interface. This implementation of the class causes OSGi Service: Hello World! to be displayed.

      1. Under the com.ibm.ws.eba.helloWorld.service project, right-click the folder src, then select New > Package.

      2. Name the new package com.ibm.ws.eba.helloWorld.service.

      3. Click Finish.

      4. Right-click the new package, then select New > Class.

      5. Name the new interface implementation class HelloWorldService.

      6. Click Add alongside the Interfaces field.

      7. Enter Hello, select HelloWorldEBA from the Matching items list, then click OK.

      8. Ensure that the Inherited abstract methods check box is selected.

      9. Click Finish.

      10. Provide implementation code for the inherited hello() method. Replace the line

          // TODO Auto-generated method stub

        ...with the line...

          System.out.println("OSGi Service: Hello World!");

        The complete code for the implementation class should now be as follows: 

          package com.ibm.ws.eba.helloWorld.service;
import com.ibm.ws.eba.helloWorld.api.HelloWorldEBA;
public class HelloWorldService implements HelloWorldEBA 
{
    @Override
    public void hello() 
    {
        System.out.println("OSGi Service: Hello World!");
    }
}

        • Save and close the file.

    7. Export the helloWorld service using OSGi Blueprint XML.

      A Blueprint configuration contains the bundle component assembly and configuration information. It also describes how components are registered in the OSGi service registry, or how components look up services from the OSGi service registry. This information is used at run time to instantiate and configure the required components when the bundle is started.

      1. In the project com.ibm.ws.eba.helloWorld.service, create a Blueprint XML file:

        1. Right-click the com.ibm.ws.eba.helloWorld.service project, and select New > Blueprint File.

        2. Accept the default values for all the options on this panel.

        3. Click Finish.

      2. Add a bean element to the Blueprint XML file.

        1. In the Design tab, click Add in the Overview pane.

        2. Select Bean, and click OK.

        3. Click Browse, select HelloWorldService, and click OK.

        4. In the Bean ID field, enter HelloEBA, then click OK to add the bean element.

      3. Add a service element to the Blueprint XML file.

        1. Select Blueprint in the Overview pane, and click Add.

        2. Select Service, and click OK.

        3. Click Browse alongside the Service Interface field.

        4. Enter Hello, select HelloWorldEBA from the Matching items list, and click OK.

        5. Click Browse alongside the Bean Reference field, select HelloEBA, then click OK.

        6. Click OK to add the service element.

      4. Examine the Blueprint XML source code.

        Select the Source tab. The source code should be as follows: 

        <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <bean id="helloEBA"
        class="com.ibm.ws.eba.helloWorld.service.HelloWorldService"/>
  <service id="HelloEBAService" ref="helloEBA"
           interface="com.ibm.ws.eba.helloWorld.api.HelloWorldEBA"/>
</blueprint>

        In the previous code block:

        • The bean element defines a Blueprint component to be instantiated. In this example, the bean element causes bean helloEBA to be instantiated, by calling the constructor for the com.ibm.ws.eba.helloWorld.service.HelloWorldService class.

          • The id attribute identifies the bean. Specify this attribute if the bean is referenced from elsewhere in the Blueprint information, for example from the service element.

          • The class attribute specifies which implementation class of the bean is instantiated.

        • The service element defines the registration of a component in the OSGi service registry. In this example, the service element registers the bean with the name helloEBA as a service in the OSGi service registry with interface com.ibm.ws.eba.helloWorld.api.HelloWorldEBA, specified by the interface attribute.

          • The ref attribute refers to the id of the bean to be registered. This id is defined in the bean element.

          • The interface attribute refers to the interface that the bean class implements.

        For more information, see section 121.5 "Bean Manager" and section 121.6 "Service Manager" of the OSGi Service Platform Release 4 Version 4.2 Enterprise Specification.

      5. Save and close the file.

      We might get an exception message (visible in the Problems pane) saying that there is no bin.include entry for OSGI-INF in the build properties file. If we see this message, use the quick-fix option to add the entry (right-click the problem, then select quick-fix).


    Results

    You have created two bundles, com.ibm.ws.eba.helloWorld.api and com.ibm.ws.eba.helloWorld.service. The com.ibm.ws.eba.helloWorld.service service implements the HelloWorldEBA interface that is declared in the com.ibm.ws.eba.helloWorld.api bundle, and contains the business logic and metadata needed to export the com.ibm.ws.eba.helloWorld.service service.


    What to do next

    You can now create the client bundle that uses the com.ibm.ws.eba.helloWorld.service service.


    Parent topic: Develop an OSGi application


    Related concepts

  • The Blueprint Container
  • Blueprint bundles
  • Blueprint XML
  • Services and the Blueprint Container
  • OSGi bundles and bundle archives


    Related tasks

  • Create a client bundle

    Create an OSGi application

  • Develop a composite bundle


    OSGi Service Platform Release 4 Version 4.2 Enterprise Specification
    Build OSGi applications with the Blueprint Container specification
    Best practices for developing and working with OSGi applications
    Develop enterprise OSGi applications for WebSphere Application Server

  • OSGi application design guidelines
  • Writing extensible OSGi applications