Developing an OSGi service as a Web service in IBM Lotus Expeditor

Learn how to programmatically expose an OSGi service running on IBM Lotus Expeditor as a Web service, using the the Lotus Expeditor Toolkit and IBM Rational Application Developer V6. This article also shows you how to deploy and test the service using the Lotus Expeditor runtime.


John Hsu (, Software engineer, IBM

John Hsu is a software engineer at the IBM China Software Development Lab in Taipei, Taiwan. John has experience in software development and testing, and he is currently working on Lotus Expeditor development. He has previously published an article called “Developing an OSGi service as a Web service in IBM Lotus Expeditor” on developerWorks Lotus.

28 November 2006

Also available in Japanese

IBM Lotus Expeditor (formerly IBM WebSphere Everyplace Deployment) is a client middleware framework and tooling platform that enables connection, independent delivery, and management of applications and services. Lotus Expeditor is built on the OSGi framework and provides J2EE services such as Web services and Enterprise JavaBeans (EJBs) to clients, so you can move key components of your applications to the client. Lotus Expeditor also enables applications to perform most business operations locally, so mobile users can continue to use their applications even when they don't have network connectivity and to synchronize with the server when the network connection becomes available.

Lotus Expeditor follows JSR-172: J2ME Web services specification to provide Web services support, but also provides features beyond the JSR-172 specification. One of these features is the IBM WebSphere Web Services Gateway, which maps OSGi services to Web services and vice versa. Thus, using Java APIs for XML-based Remote Procedure Call (JAX-RPC), applications running outside Lotus Expeditor can invoke the OSGi services running on Lotus Expeditor.

Lotus Expeditor provides the Web Services Gateway Utility to help users expose their OSGi services as Web services through rich client user interfaces. This can, however, be inconvenient in some cases. For example, when you develop an application and want to distribute it to many clients, you obviously don’t want to tell each user to open his Web Services Gateway Utility and to expose the service manually. Rather you want do this programmatically, and this article tells you how to develop an easy OSGi service bundle and how to expose it as Web services through the development toolkit provided by Lotus Expeditor.


To get the most out of this article, you should be familiar with Java, J2EE, Web services, the OSGi framework, and plug-in development using IBM Rational Application Developer V6 for WebSphere Software or Eclipse 3.x. Before completing the steps listed below, you must have either Rational Application Developer V6 or Eclipse 3.2 with the Lotus Expeditor Toolkit V6.1 installed. You also need Lotus Expeditor Client installed.

You can download a trial version of Rational Application Developer V6 from developerWorks.

In this article, you perform the following tasks:

  • Create a Client Services project that registers an OSGi service.
  • Expose the OSGi service as a Web service.
  • Deploy the Client Services project.
  • Test the deployed Web service.

Creating a Client Services project that registers an OSGi service

Let's get started by creating an OSGi service that you can expose as a Web service. In the Lotus Expeditor Toolkit, this is done by creating a Client Service project. This article assumes that you already have installed Rational Application Developer and the Lotus Expeditor Toolkit. The toolkit extends the Rational Application Developer environment and allows you to build OSGi-based and Eclipse-based applications.

Follow these steps to create the OSGi service in Rational Application Developer, but remember that you can do the same thing in Eclipse if you have the Lotus Expeditor Toolkit installed:

  1. In Rational Application Developer, switch to Plug-in Development perspective by choosing Window - Open Perspective - Plug-in Development.
  2. Choose File - New - Project.
  3. In the New Project wizard, select Client Services Project, and then click Next (see figure 1).
    Figure 1. New Project wizard
    New Project wizard
  4. In the Client Service Project panel, type WSGateway in the Project name field, and then click Next.
  5. In next wizard panel, accept the defaults and click Finish.
  6. After the Client Service project is created, choose File - New - Interface, and enter the interface name OSGiService and the package name wsgateway. Rational Application Developer creates the public interface OSGiService for you. Listing 1 shows the interface code. The getResult method is a test method. Because you are developing an OSGi service and exposing it as a Web service, both services need at least one public method for others to call it.

    Listing 1. OSGiService interface
    package wsgateway;
    public interface OSGiService {
    	public String getResult();
  7. Next, choose File - New - Class, and enter the class OSGiServiceImpl and package name wsgateway. When you create an OSGi service or a Web service, the common practice is to create an interface and an implementation class. This is a best practice that makes your code more flexible, but it is not necessary. You can create a class and register it as OSGi service and as a Web service. We do not prohibit that in Lotus Expeditor Toolkit, but we don't recommend that you do that. Listing 2 shows the implementation class.

    Listing 2. OSGiServiceImpl class
    package wsgateway;
    public class OSGiServiceImpl implements OSGiService {
    	public String getResult() {
    		return "This is OSGiServiceImpl";
  8. Add the code in listing 3 to the start() of to register OSGiService for the OSGi framework:

    Listing 3.
    public void start(BundleContext context) throws Exception {
         Hashtable properties = new Hashtable(7);
    properties.put(Constants.SERVICE_PID, wsgateway.OSGiService.class.getName());
    context.registerService(wsgateway.OSGiService.class.getName(), new OSGiServiceImpl(),_
  9. When you are done, you can run the Client Services project to determine if it can register a service to the OSGi framework. In Rational Application Developer, choose Run - Run.
  10. In the Run dialog box, select Client Services, and then click New.
  11. Select the Plug-ins tab, deselect Workspace Plug-ins, and select WSGateway (see figure 2).
  12. Click the Add Required Plug-ins button, and then click Run.
    Figure 2. Run dialog box Plug-ins tab
    Run dialog box Plug-ins tab
  13. Select the Console tab, and then enter ss and find the bundle number of WSGateway (see figure 3).
    Figure 3. Console
  14. After you locate the WSGateway bundle number, enter start xxx in the console, where xxx is the bundle number of WSGateway.
  15. Then enter s in the console, and make sure the wsgateway.OSGiService is registered to the OSGi framework (see figure 4).
    Figure 4. Console showing wsgateway.OSGiService
    Console showing wsgateway.OSGiService

Exposing the OSGi service as a Web service

After you create the OSGi service and successfully register it with the OSGi framework, you can expose the OSGi service as a Web service. Add the following code in listing 4 to the start() method of

Listing 4.

public void start(BundleContext context) throws Exception {
     Hashtable properties = new Hashtable(7);
     WebServiceProvider provider;
String providerName = "";
ServiceReference ref = context.getServiceReference(providerName);
provider = (ref == null) ? null : (WebServiceProvider)context.getService(ref);

properties.put(Constants.SERVICE_PID, wsgateway.OSGiService.class.getName());

context.registerService( wsgateway.OSGiService.class.getName(), new OSGiServiceImpl(),_

/*	provider.exportPid(wsgateway.OSGiService.class.getName());

System.out.println(wsgateway.OSGiService.class.getName() + " exposed as a Web Service at_
http://localhost:8777/ws/pid/" + wsgateway.OSGiService.class.getName());*/
ref = context.getServiceReference (wsgateway.OSGiService.class.getName());
	String sid = ref.getProperty("").toString();
	System.out.println(wsgateway.OSGiService.class.getName() + " 
exposed as Web Service at http://localhost:8777/ws/sid/" + sid);

Note that there are two ways to expose the OSGi service as a Web service: service sid or pid. The bold code in the previous listing is the common code for both methods, while the last lines of code beginning with ref = context.getServiceReference (wsgateway.OSGiService.class.getName()); are for the sid method. The commented code is for the pid method.

Import in, and then open MANIFEST.MF under the META-INF folder, and switch to the Dependencies tab (see figure 5).

Figure 5. Dependencies tab
Dependencies tab

In the Required Plug-ins section, click the Add button. In the Plug-in Selection box, enter in the Select a Plug-in field and click OK.

Deploying the Client Services project

You have done the work of adding necessary code and configurations to make your OSGi service a Web service. Now you need to deploy the Client Services project to your Lotus Expeditor runtime. (Unlike common J2SE applications, which need to run with java.exe, most J2EE applications must be deployed to a J2EE application server. In this article, we deploy it to our Lotus Expeditor runtime, which provides some J2EE application server functions.

Follow these steps to deploy the Client Services project:

  1. Repeat steps 9 - 13 in the "Creating a Client Services project that registers an OSGi service" section earlier (skip step 10 because you already have a configuration). In step 11, select the Arguments tab and change to 8777 (see figure 6).
    Figure 6. Arguments tab
    Arguments tab
  2. In the console, find and org.eclipse.equinox.http and start them.
  3. Again in the console, find WSGateway and start it.
  4. Open a Web browser and enter the URL shown in the console. You should see the Web Services Description Language (WSDL) if successful (see figure 7).
    Figure 7. WSDL in a Web browser
    WSDL in a Web browser

Testing the deployed Web service

Now that you have deployed your Web service, you want to make sure that you were successful. Lotus Expeditor Toolkit provides a simple way to do it. As long as you have a WSDL file, Lotus Expeditor Toolkit can parse it and generate the necessary stub code according to JSR 172, and then you can use these stubs to test your Web service.

Follow these steps to test your deployed Web service:

  1. Repeat steps 1 - 5 in the "Creating a Client Services project that registers an OSGi service" section above to create another Client Services project with the project name of WSGatewayClient.
  2. Choose File - New - Other.
  3. Select Client Services - Mobile Web Services - Mobile Web Services Client, and then click Next (see figure 8).
    Figure 8. New wizard
    New wizard
  4. Specify the following values in the fields in the Mobile Web Service Client dialog box (see figure 9):
    Figure 9. Mobile Web Services Client dialog box
    WSDL in a Web browser
  5. Click Next and then click Finish.
  6. In consumeService() of in WSGatewayClient, add the code in listing 5. This code calls the stubs generated by the Lotus Expeditor Toolkit.

    Listing 5. consumeService()
    private void consumeService() throws Exception {
    wsgatewayclient.OSGiServiceSoap_Stub stub = new wsgatewayclient.OSGiServiceSoap_Stub();
  7. Make sure your WSGateway service is using the pid method to expose Web services. If you use sid, you must ensure that the sid number in the WSDL URL is correct when you create the client because this may change if you add -clean as your program argument.
  8. Stop the Lotus Expeditor runtime launched in the previous section, and then run Lotus Expeditor runtime again by repeating steps 1-3 in the "Deploying the Client Services project" section, selecting WSGateway and WSGatewayClient in step 1.
  9. Type ss to find the bundle ID of WSGatewayClient and start it. You should see the result printed on the console tab (see figure 10).
    Figure 10. Console


This article showed you how to programmatically expose an OSGi service running on Lotus Expeditor as a Web service with the Lotus Expeditor Toolkit installed on Rational Application Developer. Although you can do this through GUI tools on a single client, doing it programmatically helps significantly when you need to perform a mass installation or to update this kind of service on many clients automatically. This feature also helps expose every service running on Lotus Expeditor as a Web service and thus can be invoked outside of Lotus Expeditor. This means that Lotus Expeditor provides good interoperability with other applications--one of many reasons that make Lotus Expeditor a good framework on which to build Service-Oriented Architecture solutions.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

ArticleTitle=Developing an OSGi service as a Web service in IBM Lotus Expeditor