Exporting
OSGi to Web Services Manual
Author: José M. Reyes Álamo (jmreyes@cs.iastate.edu)
In this manual we will guide you into
the process of creating simple OSGi bundles, OSGi services and exporting
these as Web Services. For this tutorial you should use the Eclipse
Ganymede Version which has full support for Web Services. You can Eclipse
download Ganymede at http://www.eclipse.org/downloads/
Download and install
knoflerfish OSGi
We are assuming this is the first time
you ever use OSGi ad Web Services. The first step is to download a copy
of the OSGi framework. There are several implementations of the OSGi
framework. The one we chose is the knopflerfish because it very complete
and has a nice GUI making it easier to use. To get your copy of the
knopflerfish OSGi framework follow these instructions:
Visit www.knopflerfish.org and go to the downloads section
Download the complete OSGi
framework Version 2.2
Install the framework following
the instructions on screen
How to create a
simple bundle
The basic unit of deployment in OSGi
is the bundle. A bundle is a JAR file that contains a manifest file,
and activator class, and additional classes and documentation. Eclipse
is entirely based on OSGi. Breaking down applications into bundles of
independent units allows to easily start/stop/update these without disrupting
then entire system. In the case of Eclipse for example you start, install
or uninstall a plug-in on the fly without the need to restart the framework
all the time. This is so because Eclipse plug-ins really are OSGi bundles.
Using these properties about Eclipse we want to take advantage of it.
We want to use the plug-in development mechanism to develop OSGi bundles
and services. To create a follow these intructions:
Open File > New >
Other > Plug-in Development > Plug-in Project. You should see
a screen like the one above
Click Next
Enter the bundle details.
In this example case call it “SayMyNameBundle” (see the screen above)
and click the “Next” button
Check the different options.
Make sure the “generate activator …” box is checked (see the
screen above)
A few available templates
are available. For the purpose of this demo choose Hello OSGi Bundle
After different class files
are created, go to SayMyName > src > saymynamebundle > Activator
class and edit the code in the start method to
System.out.println(“Hello YOURNAME”);
or other appropriate welcome message.
Do a similar modification for the
stop method but with a goodbye message.
CLICKHERE
When finished go to the
manifest file which is found in SayMyNameBundle > META-INF > MANIFEST.MF
and click on “Export deployable plug-ins and fragments” as shown
above
Choose an appropriate destination
for your bundle and click finish
After creating your bundle
go to the destination location and after starting the OSGi framework,
deploy the bundle within the framework. If you are using knopflerfish,
you can drag-and-drop the jar file just created into the GUI.
CLICKHERE
After deploying your bundle
you should be able to start it. To do so, click on the start bundle
button as show in the screenshot above.
Congratulations you just created
your Say My Name Bundle!!!
How to create an OSGi Service
An OSGi services is created in a similar
way as an OSGi bundle. In reality an OSGi Service is also a bundle,
with the difference that a service will have an interface specifying
the methods the services provides plus an implementation of those methods.
Also a service can be imported/exported so that other bundles can use/provide
the functionality. The example we will see below will provide a simple
calculator service. Let’s start then
Open File > New >
Other > Plug-in Development > Plug-in Project just as the previous
example for creating a bundle.
Give the project an appropriate
name in this case let’s call it “Calculator Service” click next
In the templates screen
select “Hello OSGi Service” as shown above and click finish
The wizard creates a set
of classes under the src folder. You should see 3 classes: Activator,
HelloService and HelloServiceImpl
Rename “HelloService”
to “CalculatorService”
Now go to the class CalculatorService.
You should see two methods, speak() and yell(). Delete both and instead
add the following method propotypes:
public int add(int x, int y);
public int substract(int x, int
y);
public int multiply(int x, int
y);
public int divide(int x, int y);
Rename “HelloServiceImpl”
to “CalculatorServiceImpl”
Add the following code for
implementing the methods
public int add(int x, int
y){
return
x + y;
}
Do the appropriate operation for
substract, multiply and divide (we are assuming the user will not attempt
dividing by zero)
Now we want to get rid of
some code added by the wizard which is not needed. Go to the Activator
class, and in the start() method delete the last two lines:
service.speak();
service.yell();
Also rename the “helloServiceTracket”
for “calculatorServiceTracker”
CLICKHERE
When finished go to the
manifest file which is found in Calculator Service > META-INF >
MANIFEST.MF and click on “Export deployable plug-ins and fragments”
as shown above
Choose an appropriate destination
for your bundle and click finish
After creating your bundle
go to the destination location and after starting the OSGi framework,
deploy the bundle within the framework. If you are using knopflerfish,
you can drag-and-drop the jar file just created into the GUI.
CLICKHERE
After deploying your bundle
you should be able to start it. To do so, click on the start bundle
button as show in the screenshot above.
Congratulations you just created
your Calculator Service!!!
How to export an OSGi services as
a Web Service
A bundle repository is a remote directory
where you can download bundles developed by other and made available.
You can enhance the OSGi framework functionalities by adding bundles
from different repositories. We will use the knopflerfish repository
to add Web Services capabilities to our framework. We need to add the
axis bundle to enable Web Services. Axis is a SOAP implementation done
by Apache. In order to add the axis bundle follow these steps:
Open the knopflerfish framework
Click on “Bundle Repository”
tab
In that tab, go to the folder
called “service”
Look for the “axis-osgi
0.1.0” (NOTE: Do not use the service called axis2-osgi 1.3 as there
are some unresolved compatibility issues)
CLICKHERE (2)
CLICKHERE (1)
Click the button “Install
and start from OBR”
Wait a few seconds up to
a few minutes. Several bundles will be installed which are necessary
for the axis bundle to run.
If the axis bundle is not
started automatically proceed to start it like any other bundle. (NOTE:
The axis bundle stops each time you shutdown the framework so
you will need to start it again after initiating the framework.)
Now your OSGi framework is ready
to support Web Services
In order to be able to export an
OSGi Services as a Web Services you need to add a property to the bundle
that will indicate the Web Services name to be used by the SOAP bundle
(in our cases the axis bundle). To continue with our example of the
“CalculatorService” we will add the necessary code in order to export
it as a Web Service.
Go to the Activator class
in the Calculator Service Project
In the start method class,
add the following lines of code:
Hashtable props = new
Hashtable();
props.put("SOAP.service.name",
"CalculatorService");
context.registerService(Demo1.class.getName(),
demo1, props);
Here CalculatorService is the name
of the exported Web Service.
Modify the line of code:
Context.registerService(CalculatorService.class.getName(),
service, new Hashtable());
By Context.registerService(CalculatorService.class.getName(),
service, props);
That way you will be using the
property just defined in step 2
After these small changes
in the code, when finished go to the manifest file again and click on
“Export deployable plug-ins and fragments”
Choose and appropriate destination
for your service and click finish
After creating your service
go to the destination location and after starting the OSGi framework,
deploy the service within the framework. If you are using knopflerfish,
you can drag-and-drop the jar file into the GUI.
After deploying your service
you should be able to start it. To do so, click on the start bundle
button just as you did to start the first bundle.
How to see
the exported Web Service.
In order to see the exported Web Services
go to the following URL: http://localhost:8080/axis/services
Here you should be able to see all
the OSGi Services exported as Web Services by the framework, yours included.
If you followed the example above, then you should see a service called
“CalculatorService” with four methods: add, subtract, multiply and
divide. There should be also a link to see the wsdl file. Here is a
screenshot
Testing the Web Service:
From now on the service you just exported
can be seen as a Web Service and all the operations that can be performed
with Web Services can also be performed with this exported service.
The following is a simple test to ensure the exporting process worked
well.
To test the web services do the following:
Open Eclipse
Make sure you are using
the Java EE perspective
CLICKHERE
Click on “Launch Web Services
Explorer” (see screenshot above)
CLICKHERE (2)
CLICKHERE (1)
Click on “WSDL Page”
then on “WSDL Main” (see screenshot above)
After that go back to your
web browser, to the URL of your services (http://localhost:8080/axis/services) and click the wsdl button next to your service
name. In the address bar, you will find the URL of the WSDL file. Copy
it.
PASTEHERE
Paste the WSDL URL into
the box in Eclipse and click GO
You should be able to see
the four methods (add, subtract, multiply, divide) listed. Click one
of them, enter values for x and y, then click GO. In the status section
below, you should be able to see the message result.
Registering the OSGi->Web
Service into a UDDI registry
Web Services use UDDI registries
to easily locate services. Different tools make use of these UDDI registries
to perform composition and when looking for services. We will show you
in the next few steps how to register the service we just created into
a UDDI server running in the Smart Home Lab.
Go to Eclipse and make sure
you are in the Java EE perspective
CLICKHERE (1)
CLICKHERE (2)
Click on “UDDI Page”
then click on “UDDI Main”
Fill the Registry Name entry
In the “Inquiry URL”
enter: http://avalon.cs.iastate.edu:8080/juddi/inquiry and click the Go button
Scroll down and click on
the “Publish” link
In the “Publish” combo
box, choose “Service Interface”
In “Publication Format”
choose Simple
In “Publish URL” enter http://avalon.cs.iastate.edu:8080/juddi/publish
In the “User ID” use
“juddi”, “Password” use “juddi”
In the “WSDL URL” use http://localhost:8080/axis/services/CalculatorService?wsdl which is the address of the WSDL file created
by the axis service running in the OSGi framework
In the “Name” enter
CalculatorServiceYOURUSERNAME (to distinguish it)
In the “Description”
enter an appropriate description and click “GO”
After you are done a screen
like the one above should appear listing all the details of the registration
process. The most important piece of data is the unique ID given to
your service (the uuid)
Now you successfully create an
OSGi Service, exported as a Web Services and registered in UDDI
registry. You can now develop Web Service applications using the WSDL
file generated by the axis bundle or use tools to compose web services
that need a UDDI registry. More details on this later.
How to manually compose Web Services:
What we want to do now is to combine
several web services together to develop more sophisticated applications.
In this example we will use one of the services available in the ISU
Smart Home Lab, and another Web Services provided by a third party.
The tutorial will get the temperature from the Smart Home Lab, which
returns the temperature in Fahrenheit degrees and we will use a third
party service to convert the temperature to Celsius degrees and display
them both. Let’s get started:
Create a new Java Project
in Eclipse by going to File > New > Other > Java > Java
Project
Give the project a name
like Temperature SHL (SHL stands for Smart Home Lab) and click finish
We have developed several
Web Services in the smart home lab. Go to http://smarthome1.cs.iastate.edu:8080/axis/services to see a list of them. From these services,
choose TemperatureService by clicking the link (wsdl) next to it. You
should see an XML file as shown above
Now copy the link from the
address bar of your browser.
Now return to Eclipse and
go to the project folder (Temperature SHL) and right-click on it and
go to New > Other > Web Services > Web Services Client
Configuration Bar
In the Service Definition
field paste the wsdl file for the TemperatureService as shown above
(http://smarthome1.cs.iastate.edu:8080/axis/services/TemperatureService?wsdl) and make sure that the configuration bar
is set to Deploy Client as shown by the arrow above. Click finish. This
will import the Temperature Web Service so that you can use it from
your application.
Now we will import the third
party Web Service to convert the temperature doing a similar process.
Go to the project folder (Temperature SHL) and right-click on it and
go to New > Other > Web Services > Web Services Client
In the Service Definition
field paste the following wsdl file (http://seekda.com/goto?uri=http%3A%2F%2Fnetpub.cstudies.ubc.ca%2Fws01%2Fwscs01%2FconversionService.asmx%3FWSDL ) for the Convert Temperature Service . Again
make sure that the configuration bar is set to Deploy Client. Click
finish.
Now you have two extra package
in your project folder: edu.iastate.cs.smarthome1.axis.services.TemperatureService
and org.tempuri
Now create a Java class
in your project by right clicking your project folder and going to New
> Class. You can call it Temps
Make sure you import the
two packages, call the Temperature Service and then convert the temperature
to Celsius. The code for doing this is provided below:
import edu.iastate.cs.smarthome1.axis.services.TemperatureService.*;
import org.tempuri.*;
public class TestWS {
public
static void main (String args[]){
float tempF;
try {
TempServiceImplProxy shTemp = new TempServiceImplProxy();
tempF = shTemp.getTemperature();
System.out.println("Smart Home Temp in
F is: " + tempF);
ConversionServiceSoapProxy celTemp = new ConversionServiceSoapProxy();
System.out.println("Smart Home Temp in
C is: " + celTemp.celsius(tempF));
}
catch (Exception e){
e.printStackTrace();
}
}
}
After that test you class
and you should see the temperature reading and the conversion displayed.
Congratulations you just manually
composed two Web Services!!!
Additional Resources:
For more information and tutorials
on how to use Web Services within Eclipse go to:
http://www.eclipse.org/webtools/jst/components/ws/1.5/tutorials/index.html
If you are interested in looking for
more Web Service available you can visit: http://seekda.com/ and http://www.xmethods.net/ve2/index.po