...
The greeter demo can be found in the samples/greeter directory of the SVN code base and implements a simple OSGi Greeter Service and a consumer to that service with a trivial UI.
In this walkthrough all the required bundles are installed straight from the maven release repository, so no need to check out SVN and build anything to get started with the Greeter Demo.
The Greeter demo design
The demo is composed of 3 bundles:
- The Greeter Interface bundle
- The Greeter Service Implementation bundle
- The Greeter Service Consumer bundle
The Greeter Interface bundle exports the GreeterService
interface which both other bundles depend on. This is the interface:
Code Block | ||||
---|---|---|---|---|
| ||||
public interface GreeterService { Map<GreetingPhrase, String> greetMe(String name); GreetingPhrase [] greetMe(GreeterData name) throws GreeterException; } |
The GreeterData
interface, GreetingPhase
and GreeterException
classes are
...
custom types defined in the Greeter Interface bundle.
In this walkthrough, the following setup will be used:
The client side bundles will be running in Equinox, invoking on a Distributed OSGi Service running in Felix. Note that the choice of containers is completely trivial. Any OSGi container that implements the Service Registry Hooks (a new feature in OSGi 4.2) can be used on either side.
The Server Side
The Greeter Service implementation bundle provides a trivial implementation of the GreeterService interface. Additionally, it has an Activator:
Code Block | ||||
---|---|---|---|---|
| ||||
public class Activator implements BundleActivator { private ServiceRegistration registration; public void start(BundleContext bc) throws Exception { Dictionary props = new Hashtable(); props.put("osgiservice.remoteexported.interfaces", "*"); props.put("osgiservice.remoteexported.configuration.typeconfigs", "pojoorg.apache.cxf.ws"); props.put("osgiorg.remoteapache.configurationcxf.pojows.address", "http://localhost:9090/greeter"); registration = bc.registerService(GreeterService.class.getName(), new GreeterServiceImpl(), props); } public void stop(BundleContext bc) throws Exception { registration.unregister(); } } |
Besides creating the service instance, the activator sets the additional properties on the service that are required to make it available remotely:
- The
osgiservice.remoteexported.interfaces
property is set to '*
', which means that all the interfaces passes to registerService are good for remotingshould be made accessible remotely. In this case it's just theGreeterService
interface. - The
osgiservice.remoteexported.configuration.typeconfigs
is set topojo
org.apache.cxf.ws
, which is a CXF specific configuration type that can be used to set the URL at which expose the OSGi Service as a Web Service over SOAP/HTTP. The address of the service is to be exposed. This is done specified via theosgiorg.remoteapache.configurationcxf.pojows.address
property.
Let's run the server in Felix 13.40.1. As a prerequisite it requires some of the OSGi Compendium Specification interfaces. These don't come with the Felix download but are built as part of the Felix build. When building a distribution, the Felix bundle with these interfaces is pulled in via Maven and put in the target/deps directory, but you can install a bundle that contains these interfaces straight from Maven.
In this walkthrough I'm using the single-bundle distribution of CXF/DOSGi which can be installed straight from the Maven release repository.
To set up my Felix environment, I'm running the following commands:
Code Block |
---|
C:\felix-framework-13.4.1>java -jar bin\felix.jar0.1> Welcome to Apache Felix. ================= -> ps START LEVEL 1 ID State Gogo g! install http://repo1.maven.org/maven2/org/osgi/org.osgi.compendium/4.2.0/org.osgi.compendium-4.2.0.jar g! start http://www.apache.org/dist/cxf/dosgi/1.2/cxf-dosgi-ri-singlebundle-distribution-1.2.jar ... some log messages may appear... g! lb 0|Active Level| Name [ 0|org.apache.felix.framework 0] [Active(3.0.1) 1|Active ] [ | 0] System Bundle 1|org.apache.felix.bundlerepository (1.46.12) [ 1] [2|Active ]| [ 1] Apache Felix Shell Service (1.0.2) [ 2] [1|org.apache.felix.gogo.command (0.6.0) 3|Active ]| [ 1] Apache Felix Shell TUI (1.0.2) [ 3] [1|org.apache.felix.gogo.runtime (0.6.0) 4|Active ]| [ 1] Apache Felix Bundle Repository (1.2.1) -> start file:/<dosgi-root>/distribution/single-bundle/target/deps/org.osgi.compendium-11|org.apache.felix.gogo.shell (0.6.0) 5|Resolved | 1|osgi.cmpn (4.2.0.jar -> start file:/<dosgi-root>/distribution/single-bundle/target/200908310645) 6|Active | 1|cxf-dosgi-ri-singlebundle-distribution- (1.0-SNAPSHOT.jar 2.0) |
Some log meesages messages may come up now.
Note that instead of manually adding these bundles to the Felix container, you can also append the target/felix.config.properties.append
file to the <felix-root>/conf/config.properties file. This will automatically load these two bundles when Felix starts up.
Now let's start up the server-side greeter bundles. Like with the DOSGi bundle itself, I'm installing these straight from the Maven release repository.
Code Block |
---|
-> g! start file:/<dosgi-root>/samples/greeter/interface/targethttp://repo1.maven.org/maven2/org/apache/cxf/dosgi/samples/cxf-dosgi-ri-samples-greeter-interface/1.2/cxf-dosgi-ri-samples-greeter-interface-1.0-SNAPSHOT2.jar ->g! start filehttp:/<dosgi-root>//repo1.maven.org/maven2/org/apache/cxf/dosgi/samples/greeter/impl/targetcxf-dosgi-ri-samples-greeter-impl/1.2/cxf-dosgi-ri-samples-greeter-impl-1.0-SNAPSHOT2.jar -> ps... some log messages will appear ... g! lb START LEVEL 1 ID |State Level |Level|Name [ 0] [|Active ]| [ 0] |System Bundle (13.40.1) [ 1] [|Active ]| [ 1] |Apache Felix ShellBundle ServiceRepository (1.06.2) [ 2] [|Active ] [| 1] |Apache Felix ShellGogo TUICommand (10.6.0.2) [ 3] [|Active ] [| 1] |Apache Felix BundleGogo RepositoryRuntime (10.26.10) [ 4] [Active ] [ 1] OSGi R4 Compendium Bundle|Active | 1|Apache Felix Gogo Shell (0.6.0) 5|Resolved | 1|osgi.cmpn (4.12.0.200908310645) [ 5] [6|Active ] [| 1] |Distributed OSGi Distribution Software Single-Bundle Distribution [ 8] [7|Active ]| [ 1] |CXF Distributed OSGi Greeter Demo Interface Bundle [ 9] [8|Active ]| [ 1] |CXF Distributed OSGi Greeter Demo Service Implementation Bundle |
At the end of the log messages you will see one appear that says: INFO: TopologyManager: export sucessful Endpoints: Endpoint Description for ServiceReference [
Some more log messages come up. When it says INFO: Remote org.apache.cxf.dosgi.samples.greeter.GreeterService
endpoint has been published into Discovery service you know ]
This means that the service is successfully exposed remotely, and you can verify this by requesting the WSDL:
This WSDL was dynamically generated from the exposed GreeterService
Java interface. Under the hood, the Aegis data binding is used for this.
The Service Consumer side.
The Service Consumer Java code contains no specific Distribution-related elements. It's simply an Activator
that creates a ServiceTracker
listening for services that implement the GreeterService
interface. When the service becomes available it opens a little GUI window that asks you for an argument that can be sent to the Greete Greeter service. See here for the actual code
Tip |
---|
Note that in many cases using an OSGi Component Framework such as Spring-DM, iPojo or OSGi DS is highly recommeded when writing OSGi Service Consumers. OSGi Services are highly dynamic in nature. They can come and go. Using a component framework will generally save you from writing |
So the remote service is simply looked up the normal way, via the OSGi Service Registry.
How does it get there? The fact that a lookup on a service is done internally triggers a Service Registry Hook. This will go out to any registered Distributed OSGi Discovery implementations and query them for any matching services.
However, in our setup we haven't yet registered a Discovery implementation. There is an alternative, more static way to provide discovery type information, in case this info is not available via discovery. It can be specified in a OSGI-INF/remote-service/*.xml
file. This the content of the Greeter Service Consumer remote-services.xml file:
Code Block | ||||
---|---|---|---|---|
| ||||
<service<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/sdrsa/v1.0.0"> <service<endpoint-description> <provide<property interfacename="orgobjectClass"> <array> <value>org.apache.cxf.dosgi.samples.greeter.GreeterService" />GreeterService</value> </array> <property name="osgi.remote.interfaces">*</property> <property name="osgi.remote.configuration.type">pojo<endpoint.id">http://localhost:9090/greeter</property> <property name="osgi.remote.configuration.pojo.address">http://localhost:9090/greeter<service.imported.configs">org.apache.cxf.ws</property> </serviceendpoint-description> </serviceendpoint-descriptions> |
TheLet's run the consumer in Equinox, so that we have a bundle the bundles running in Equinox talking to a remoted service running in Felix!
As with Felix, we will have to load the bundle with the OSGi compendium interfaces. There's one that ships with Equinox.
Code Block |
---|
/eclipse> java -jar plugins/org.eclipse.osgi_3.56.0.v20081201-1815v20100517.jar -configuration conf -console osgi> install install file:plugins/org.eclipse.osgi.services_3.2.0100.v20081205-1800v20100503.jar Bundle id is 1 osgi> start 1 osgi> install filehttp:/<dosgi-root>/distribution/single-bundle/target//www.apache.org/dist/cxf/dosgi/1.2/cxf-dosgi-ri-singlebundle-distribution-1.0-SNAPSHOT2.jar Bundle id is 2 osgi> start 2 ... some log messages may appear... |
Some logging messages may appear. You can also automatically load the DOSGi bundles by appending the target/equinox.config.ini.append to you equinox config.ini file.
Code Block |
---|
osgi> install file:/O:http://repo1.maven.org/maven2/org/apache/cxf/dosgi/samples/greeter/interface/targetcxf-dosgi-ri-samples-greeter-interface/1.2/cxf-dosgi-ri-samples-greeter-interface-1.0-SNAPSHOT2.jar Bundle id is 3 osgi> install file:/O:http://repo1.maven.org/maven2/org/apache/cxf/dosgi/samples/greeter/client/targetcxf-dosgi-ri-samples-greeter-client/1.2/cxf-dosgi-ri-samples-greeter-client-1.0-SNAPSHOT2.jar Bundle id is 4 osgi> ss Framework is launched. id State Bundle 0 ACTIVE org.eclipse.osgi_3.56.0.v20081201-1815v20100517 1 ACTIVE RESOLVED org.eclipse.osgi.services_3.2.0100.v20081205-1800v20100503 2 ACTIVE cxf-dosgi-ri-singlebundle-distribution_1.0.0.SNAPSHOT 3 INSTALLED cxf-dosgi-ri-samples-greeter-interface_1.0.0.SNAPSHOT 4 INSTALLED cxf-dosgi-ri-samples-greeter-client_1.0.0.SNAPSHOT osgi> start 4 |
After a few moments the following window appears:
The window appears once This means that the ServiceTracker in the consumer has received a callback that the GreeterService
has been found. The value entered will used to invoke the (remote) OSGi service, with a call like this:
Code Block |
---|
Map<GreetingPhrase, String> result = greetergreeterService.greetMe("foobar"); |
I can see that the invocation has been received by the service implementation as in the Felix window the following appears.
...