+

Search Tips   |   Advanced Search

Create a client bundle

For the simple HelloWorld OSGi application, the client bundle calls the HelloWorldService service, and uses it to produce the message OSGi Service: Hello World!.

This task assumes that we have already created the HelloWorldService service, as described in Create a service bundle.

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 a bundle called com.ibm.ws.eba.helloWorld.client. This bundle uses the HelloWorldService service that is exported by the bundle com.ibm.ws.eba.helloWorld.service, as described in Create a service bundle.

  • Demonstration of this task (7 min)

    To create the client bundle...

    1. Create an OSGi bundle project.

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

      2. Configure the project.

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

        • 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. Make the HelloWorldEBA interface available to the client implementation bundle.

      Edit the client bundle manifest to make classes inside the com.ibm.ws.eba.helloWorld.api package available to the client 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.client 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 box, enter com.ibm.ws.eba, select com.ibm.ws.eba.helloWorld.api (1.0.0) 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 box, set the minimum version to 1.0.0 Inclusive, and set the maximum version to 2.0.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,2.0.0).

        This version syntax means "exported packages with versions between 1.0.0 inclusive and 2.0.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 client bundle uses an updated version of the package if it differs in the value of the minor version or the micro version, but not the major version, because only a binary incompatible change, such as the deletion of a public method, can cause the client bundle to cease functioning correctly.

      8. Save and close the file.

    3. Create a class HelloWorldClient.

      1. In the project source folder src, create a package called com.ibm.ws.eba.helloWorld.client. In the package, create a class called HelloWorldClient with the following contents: 
        package com.ibm.ws.eba.helloWorld.client;

import com.ibm.ws.eba.helloWorld.api.HelloWorldEBA;

public class HelloWorldClient {
    private HelloWorldEBA helloWorldEBAService = null; //a reference to the service

    public void refHello() {
        System.out.println("Client: Start...");
        helloWorldEBAService.hello();
        System.out.println("Client: End...");
    }

    public HelloWorldEBA getHelloWorldEBAService() {
        return helloWorldEBAService;
    }

    public void setHelloWorldEBAService(HelloWorldEBA helloWorldEBAService) {
        this.helloWorldEBAService = helloWorldEBAService;
    }
}

        In the previous code block:

        • The line HelloWorldEBA helloWorldEBAService = null; defines the service dependency.

        • The line helloWorldEBAService.hello(); demonstrates that a service has been injected for the helloWorldEBAService dependency.

      2. Save and close the file.

    4. Create a Blueprint configuration.

      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.client, create a Blueprint XML file:

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

        2. Optional. Specify the file name. This can be any name provided it is an XML file. For example, helloWorldRef.xml.

        3. Leave the other options as the default values.

        4. Click Finish.

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

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

        2. Select Reference, and click OK.

        3. Click Browse alongside the Reference Interface field.

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

        5. In the Reference ID field, enter helloEBARef, then click OK to add the reference element.

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

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

        2. Select Bean, and click OK.

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

        4. Click OK to add the bean element.

        5. In the Method References pane, click Browse alongside the Initialization method field.

        6. Select refHello() and click OK

      4. Add a property to the bean.

        1. Select HelloWorldClient (Bean) in the Overview pane, and click Add.

        2. Select Property, and click OK.

        3. In the Details pane, enter helloWorldEBAService in the Name field.

        4. Click Browse alongside the Reference field.

        5. Select helloEBARef and click OK.

      5. Examine the Blueprint XML source code. This Blueprint file specifies the internal wiring of the components. 
        <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <reference id="helloEBARef"
    interface="com.ibm.ws.eba.helloWorld.api.HelloWorldEBA"/>
  <bean id="HelloWorldClientBean"
    class="com.ibm.ws.eba.helloWorld.client.HelloWorldClient"
    init-method="refHello">
    <property name="helloWorldEBAService" ref="helloEBARef"/> 
  </bean>
</blueprint>

        In the previous code block:

        • The init-method refHello is called when the com.ibm.ws.eba.helloWorld.client.HelloWorldClient bean is created.

        • The property element specifies how a dependency is injected.

          • The property helloWorldEBAService is set by calling the property setter public void setHelloWorldEBAService(HelloWorldEBA helloWorldEBAService). You can use setter injection for bean properties that are defined in accordance with Java™ bean conventions.

          • The attribute ref specifies the Blueprint element ID of the component to be injected. The ref attribute must match a top-level element in this file. In this case, it matches the reference element.

        • The reference element defines a dependency of this Blueprint module on an OSGi service with interface com.ibm.ws.eba.helloWorld.api.HelloWorldEBA. When the Blueprint Container starts this module, the value of the interface attribute must match an available service in the OSGi service registry. If no match can be made, the Blueprint module is not started. In this case, the service is defined in the service element of the Blueprint XML of the service bundle.

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

      6. Save and close the file.


    Results

    You have created a bundle called com.ibm.ws.eba.helloWorld.client. This bundle calls the HelloWorldService service, and uses it to produce the message OSGi Service: Hello World!.


    What to do next

    You can now create an OSGi application, in which multiple bundles are packaged together.


    Parent topic: Develop an OSGi application


    Related concepts

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


    Related tasks

  • Create a service 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