Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EIG:Install TimeService Tutorial into Apache Karaf"

(Introduction)
 
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
In ECF 3.8+ it's possible to use Apache Karaf runtime to install the ECF SDK and run remote service applications.  Once such example application is the [[Tutorial:_Building_your_first_OSGi_Remote_Service | Building your first OSGi Remote Services Tutorial]].
+
See the [[Tutorial:_Building_your_first_OSGi_Remote_Service | Building your first OSGi Remote Services Tutorial]] to understand how to design and build this example.
  
The tutorial explains how to first [[Tutorial:_Building_your_first_OSGi_Remote_Service#Service_Host:_Implement_the_Service | Implement the Remote Service]] and then [[Tutorial:_Building_your_first_OSGi_Remote_Service#Service_Host:_Register_the_Service | Register the Remote Service]].
+
Prior to running this tutorial you must [[EIG:Install_into_Apache_Karaf | install ECF Remote Services into your Karaf server]].
  
To run the remo]]te service host on Apache Karaf, it's first necessary to install the relevant bundles into the Karaf runtime.  To do this, first [[EIG:Install_into_Apache_Karaf | Install the ECF Remote Service SDK into Apache Karaf]].  Once the ECF SDK is installed you may install the Timeline Example bundles with the following feature install (may be done from the Karaf command shell or from the webconsole):
+
==Exporting the Remote Service with Karaf==
  
karaf@root()> '''feature:install -v ecf.rs.examples.timeservice'''
+
To export the remote time service host with Apache Karaf simply install the timeservice host example feature
  
Once complete, the install process should look like this
+
'''feature:install -v ecf-rs-sdk-examples-timeservicehost'''
 +
 
 +
This will install two bundles: the timeservice API bundle (com.mycorp.examples.timeservice) and the timeservice host bundle (com.mycorp.examples.timeservice.host).  When Karaf start these bundles, they are exported, and will produce the following output on console
  
 
[[File:Karafinst4.png]]
 
[[File:Karafinst4.png]]
  
Optionally, before starting the TimeService host you can turn on some extra output by issuing this command into the Apache command shell
+
The output after the EXPORT_REGISTRATION indicates that the TimeService has been exported as a remote service and is ready for remote consumer discovery and usage. 
 +
 
 +
For reference, this output is produced by the TimeService Examples Host activator class  [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.host/src/com/mycorp/examples/timeservice/host/Activator.java com.mycorp.examples.timeservice.host.Activator].  The source for the entire bundle can be found in the [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git ECF primary git repo], project path:  examples/bundles/com.mycorp.examples.timeservice.host.
 +
 
 +
==Running/Debugging the TimeService Client in Eclipse==
 +
 
 +
For this part of the tutorial, the time service consumer will be a simple OSGi client, which will run in Eclipse.  For this the prerequisites are:
 +
 
 +
#Java 1.8
 +
#Eclipse (see [https://www.eclipse.org/downloads/ here to download]) with eGit installed
 +
#ECF SDK for Eclipse (see [http://www.eclipse.org/ecf/downloads.php here to download and install])
 +
 
 +
Once the above are installed, clone the [http://git.eclipse.org/gitroot/ecf/org.eclipse.ecf.git ECF git repo] in the Git Repositories View (only master branch is needed).
 +
 
 +
[[File:Karafinst5.png]]
 +
 
 +
and then Import Projects these two projects from the examples/plugins directory:  com.mycorp.examples.timeservice.async and com.mycorp.examples.timeservice.consumer.ds.async
 +
 
 +
[[File:KarafInst6a.png]]
 +
 
 +
Open the TimeServiceComponentAsync.java source from the com.mycorp.examples.timeservice.consumer.ds.async package in the project of the same name, and place a break point on the first code line of the bindTimeService method. 
 +
 
 +
[[File:KarafInst7a.png]]
 +
 
 +
The bindTimeService method will be called by Declarative Services when the ITimeServiceAsync is discovered via Zeroconf LAN-based remote services discovery.  The instance of ITimeServiceAsync will be an ECF-constructed proxy service for accessing the remote ITimeService via the Java8 CompletableFuture.
 +
 
 +
To start the client running in the debugger, open the editor of this product file:  com.mycorp.examples.timeservice.consumer.ds.async/TimeServiceConsumer.generic.zeroconf.product.  When ready to launch the client, click on 'Launch an Eclipse Application in Debug Mode' in the lower-left part of the Overview tab.
 +
 
 +
[[File:KarafInst8a.png]]
 +
 
 +
After a few seconds the service should be discovered and the proxy injected into the bindTimeService method by declarative services, causing the Eclipse debugger to stop the client execution at the breakpoint set above.
 +
 
 +
[[File:Karafinst9.png]]
 +
 
 +
[[File:KarafInst9a.png]]
  
karaf@root()> '''system:property verboseRemoteServiceAdmin true'''
+
NOTE:  For this localhost example, the discovery provider used is Zeroconf (in bundle org.eclipse.ecf.provider.jmdns).  Zeroconf uses multicast on a LAN.  If you are not attached to a LAN, or the LAN you are on has restricted use of Zeroconf, the remote service may not be automatically discovered by the client.
  
Then using the webconsole (or the command shell) simply start the bundle named '''ECF RS Example Timeservice Host''' (com.mycorp.examples.timerservice.host).  This will produce output in the command shell (System.out) similar to the following, indicating that the service has been exported by RemoteServiceAdmin and the MyTimeService registered.
+
Allow the execution to continue and the remote method will be invoked, and the current time reported by the Karaf server's remote service will be shown in the consumer's console
  
<pre>
+
[[File:KarafInst10a.png]]
karaf@root()> Service Exported by RemoteServiceAdmin.  EndpointDescription Properties=ecf.endpoint.id=ecftcp://localhost:3288/server, ecf.endpoint.id.ns=org.eclipse.ecf.core.identity.StringID, ecf.endpoint.ts=1394381999769, ecf.generic.server.hostname=localhost, ecf.generic.server.port=3288, ecf.rsvc.id=1, endpoint.framework.uuid=0a22aaf0-e110-4a89-ac62-edd97e44b2c1, endpoint.id=a7d3c846-5304-4e34-bf43-03224a4a138f, endpoint.package.version.com.mycorp.examples.timeservice=1.0.0, endpoint.service.id=485, objectClass=Ljava.lang.String;@78d2df8c, remote.configs.supported=[Ljava.lang.String;@6faf2576, remote.intents.supported=[Ljava.lang.String;@53c49f42, service.id=485, service.imported=true, service.imported.co
+
nfigs=[Ljava.lang.String;@6faf2576}MyTimeService host registered with registration=org.apache.felix.framework.Servi
+
ceRegistrationImpl@7a627ff2
+
</pre>
+
  
For reference, this output is produced by the TimeService Examples Host activator class  '''com.mycorp.examples.timeservice.host.Activator'''
+
Also, the Karaf console will show an indication that the remote service implementation method was invoked
  
The output above indicates that the TimeService has been exported and is ready for remote consumer access.
+
[[File:Karafinst11.png]]

Latest revision as of 19:13, 12 June 2018

Introduction

See the Building your first OSGi Remote Services Tutorial to understand how to design and build this example.

Prior to running this tutorial you must install ECF Remote Services into your Karaf server.

Exporting the Remote Service with Karaf

To export the remote time service host with Apache Karaf simply install the timeservice host example feature

feature:install -v ecf-rs-sdk-examples-timeservicehost

This will install two bundles: the timeservice API bundle (com.mycorp.examples.timeservice) and the timeservice host bundle (com.mycorp.examples.timeservice.host). When Karaf start these bundles, they are exported, and will produce the following output on console

Karafinst4.png

The output after the EXPORT_REGISTRATION indicates that the TimeService has been exported as a remote service and is ready for remote consumer discovery and usage.

For reference, this output is produced by the TimeService Examples Host activator class com.mycorp.examples.timeservice.host.Activator. The source for the entire bundle can be found in the ECF primary git repo, project path: examples/bundles/com.mycorp.examples.timeservice.host.

Running/Debugging the TimeService Client in Eclipse

For this part of the tutorial, the time service consumer will be a simple OSGi client, which will run in Eclipse. For this the prerequisites are:

  1. Java 1.8
  2. Eclipse (see here to download) with eGit installed
  3. ECF SDK for Eclipse (see here to download and install)

Once the above are installed, clone the ECF git repo in the Git Repositories View (only master branch is needed).

Karafinst5.png

and then Import Projects these two projects from the examples/plugins directory: com.mycorp.examples.timeservice.async and com.mycorp.examples.timeservice.consumer.ds.async

KarafInst6a.png

Open the TimeServiceComponentAsync.java source from the com.mycorp.examples.timeservice.consumer.ds.async package in the project of the same name, and place a break point on the first code line of the bindTimeService method.

KarafInst7a.png

The bindTimeService method will be called by Declarative Services when the ITimeServiceAsync is discovered via Zeroconf LAN-based remote services discovery. The instance of ITimeServiceAsync will be an ECF-constructed proxy service for accessing the remote ITimeService via the Java8 CompletableFuture.

To start the client running in the debugger, open the editor of this product file: com.mycorp.examples.timeservice.consumer.ds.async/TimeServiceConsumer.generic.zeroconf.product. When ready to launch the client, click on 'Launch an Eclipse Application in Debug Mode' in the lower-left part of the Overview tab.

KarafInst8a.png

After a few seconds the service should be discovered and the proxy injected into the bindTimeService method by declarative services, causing the Eclipse debugger to stop the client execution at the breakpoint set above.

Karafinst9.png

KarafInst9a.png

NOTE: For this localhost example, the discovery provider used is Zeroconf (in bundle org.eclipse.ecf.provider.jmdns). Zeroconf uses multicast on a LAN. If you are not attached to a LAN, or the LAN you are on has restricted use of Zeroconf, the remote service may not be automatically discovered by the client.

Allow the execution to continue and the remote method will be invoked, and the current time reported by the Karaf server's remote service will be shown in the consumer's console

KarafInst10a.png

Also, the Karaf console will show an indication that the remote service implementation method was invoked

Karafinst11.png

Copyright © Eclipse Foundation, Inc. All Rights Reserved.