OSGi Bootcamp Workshop Exercise

1. OSGi BootcampWorkshop Exercise By Peter Kriens CEO aQute OSGi Technology Officer and OSGi Fellow

2. Setting Up The Environment • The CD contains all the tools you need: • Java 1.4.1 • Eclipse 2.0.2 • Exercise projects with source (ex dir) • Framework fwx.exe • Also available on the network \\ziggy\fwx • Install Java 1.4.1, Install Eclipse • Copy the workshop dir to c:\fwx

3. What Will We Do? • These exercises take a step by step approach to make a larger program • This program is a “See your buddies” Web page viewer • Each participant will make a Web page • This web page is automatically registered with all participants portal's • With Zero Administration …

4. Overview Browser app 1 app 2 app 3 app 4 SP 2 app2 SP 3 app3 multicast app1 SP 1 app4 SP 4

5. Architecture: Classes Thread <<interface>> BundleActivator LogService ServiceTracker Logs messages Distributor Activator HttpTracker HttpContext finds buddies Tracks http servers Tracks buddies Registers page Portal Link <<interface>> Http Service Tracks portal entries Registers /portal page

6. What Will We Learn? • Using Eclipse • Constructing an OSGi bundle • Class path management • Using the Log service • Tracking of the Http Services • Registering a servlet • Using the demo portal • Networking code

7. Create a simple bundle printing "Hello World" and "Goodbye World" at start and stop What will you learn? Construct a BundleActivator class Add a correct Manifest Place it all in a JAR file Starting the Framework Install/Uninstall a bundle 1.1 Hello World Bundle

8. 1.1 Back to Basics: Hello World <<interface>> BundleActivator Activator The Activator class will print “Hello World” when the bundle is started and “Goodbye World” when it stops.

9. 1.1 Getting Started • Assumptions • Eclipse 2.0.2 (check in Help:About, 2.0.0 does not work!) installed • Started Eclipse

10. 1.1 Eclipse

11. 1.1 Getting Started • Create new Java Project • File:New:Project • Java Project, Next • Name is “ws” • Default location, Next • Libraries, Add external jars, • servlet.jar, osgi.jar (from where you copied the files. c:\fwx\osgi.jar) • Attach source (select osgi.jar), Finish

12. 1.1 Add External Jar

13. 1.1 Setup Activator class • Add Package • File:New:Package • Name, aQute.world.congress

14. 1.1 Setup Activator • Add new class • File:New:Class • Package, aQute.world.congress • Name, Activator • Interfaces • Add BundleActivator • Finish • Eclipse will open a generated source file

15. 1.1 Activator class setup

16. 1.1 Write Hello/Goodbye World • Fill in the System.out.println(“...”) in the appropriate places • Save the file (File:Save or control-S) • This automatically compiles, so correct any errors

17. 1.1 Create The Manifest • We only define what class to start: Activator • File:New:File, name it Manifest.mf • Store in aQute.world.congress package/folder • Manifest MUST end with 2 empty lines!! • Fill in (and save):Manifest-Version: 1.0Bundle-Activator: aQute.world.congress.Activator

18. 1.1 Create Manifest

19. 1.1 Create Bundle JAR file! • Select “ws” in left pane • Press right mouse button • Select Export • Select JAR File • Next

20. 1.1 Create JAR File • Export Destination • Name it ws.jar • Save the JAR in the load directorywhere you copied fwx,e.g. c:\fwx\load • Next

21. 1.1 Create JAR file • Deselect “with compile errors” • Save the description in the “ws” workspace, under the name bundle.jardesc • Next

22. 1.1 Create JAR file • Set to use existing Manifest • Select Manifest.mf • Finish • (It is OK to create theload directory)

23. 1.1 Starting A Framework • The fwx.jar is the OSGi Reference Framework with all the R3 services reference implementations • This Framework is not optimized, nor industrialized • It expires in 60 days • Contact a vendor for a real framework • To start it, open a window on its directory and double click it • It will automatically start all bundles in the load directory • This is not standard but implemented in a bundle

24. 1.1 Starting the Framework

25. 1.1 Restarting • You can restart the bundle by • select the bundle.jardesc • Right mouse: Create Jar • This works because the fileinstall bundle on the Framework will detect that the JAR file is modified in the load directory • This will automatically update the bundle in the Framework (look at the console)

26. 1.1 What Did We Learn? • We learned how to create a real bundle • This bundle needed • An Activator class • A Manifest • These components were packed in a JAR file • This JAR file was installed and started on an OSGi Framework with the fileinstaller bundle • The console was used to see the start and stop methods

27. 1.2 Using the Log Service • Instead of using the console, change the code to use the Log Service from the registry • What will you learn in this exercise? • Use a service from another bundle • Import packages from another bundle • Get a service from the registry • Use the log service • Find out the methods of a service

28. 1.2 Using The Log Service <<interface>> BundleActivator LogService Logs messages Activator We will now use a service: The Log Service

29. Simple and small Log service for operator 4 Levels INFO, DEBUG, WARNING, ERROR Automatically logs framework events in a defined way Other bundles can access log history Management bundle Length implementation dependent Used also for accounting, notifications org.osgi.service.log v1.1Log Service

30. org.osgi.service.log v1.1Log Service a log user a log reader A log user bundle A log reader using bundle Log a message Retrieve log LogService LogEntry LogListener LogReader Service Send new log entry A log entry impl. Message log a log service impl. A log reader impl. Store a message for retrieval and broadcast Log Service Impl. bundle

31. 1.2 Prepare for the Log Service • Save the BundleContext parameter in a context instance variableBundleContextcontext;publicvoid start(BundleContext context) {this.context = context; ...}

32. 1.2 The log() method • Add a log() method to the Activator class: voidlog(Stringmsg,Throwableexception){ ServiceReferenceref=context.getServiceReference( LogService.class.getName()); LogServicelog=null; if(ref!=null){ log=(LogService)context.getService(ref); if(log!=null){ if(exception==null) log.log(LogService.LOG_INFO,msg); else log.log(LogService.LOG_ERROR,msg,exception); } context.ungetService(ref); return; } System.out.println(msg+" : "+exception); }

33. 1.2 Use the log method • Replace the calls to System.out with calls to the log() methodpublicvoid start(BundleContext context) {this.context = context; log( "Hello world", null );}publicvoid stop(BundleContext context){ log( "Goodbye world", null );}

34. 1.2 Organize Imports • Source:Organize Imports • This will automatically add the necessary import statements

35. 1.2 Contents of LogService • How can you find out what the LogService can do for you? • Use the Javadoc (on the CD) • Click on the type, open context menu (right mouse button) and select "Open Declaration" • Use the Ctrl-Space function in Eclipse

36. 1.2 Finding The Methods Type Ctrl-Space

37. 1.2 Importing • We use the Log Service, this requires the import of the org.osgi.service.log package • This is indicated in the Manifest file with the Import-Package manifest header • This header may contain any number of packages, separated with a comma, and optionally with a specification-version modifier

38. 1.2 Modify The Manifest • Edit Manifest.mf • Add Import-Package for • org.osgi.service.log Manifest-Version: 1.0 Bundle-Activator: aQute.world.congress.Activator Import-Package: org.osgi.framework, org.osgi.service.log;specification-version=1.0

39. 1.2 Using the Log Service • Save the source file (correct compile errors) • Select bundle.jardesc, right menu, Create JAR • Check the console of fwx: • Goodbye world • But no Hello world … This is now in the log • Where is the log????

40. 1.2 Viewing the Log Service • Open a telnet session • Start:Run:telnet localhost 2011 • This opens a simple OSGi console/debugger • Type • log

41. 1.2 The console • The console bundle has many functions • exports - shows package export/import • lsb - list bundles • lss - list services (can use filter) • install <uri> - install • uninstall <id> • update bundle <id> • help • Can be extended by other bundles, see org.osgi.tools.command.CommandProvider

42. 1.2 Changing the version • Verify what happens when the specfication version is modified • Set the version to 1.8 and create the JAR file

43. 1.2 What Did We Learn? • Using the Log Service • Importing a package, with version specification • Getting a service from the registry • Using the OSGi console bundle

44. 1.2a Using the Service Tracker • Track the OSGi Log Service with a Service Tracker • What will we learn? • How to efficiently track a service • Assure that a temporary absence of a service does not disrupt our program • The org.osgi.util.tracker.ServiceTracker utility

45. 1.2a Use the ServiceTracker • Create a ServiceTracker for the logServiceTrackertracker;publicvoid start(BundleContext context) {this.context = context; tracker = new ServiceTracker( context, LogService.class.getName(), null ); tracker.open();}

46. 1.2a Use The ServiceTracker • Change the log() method to use the trackervoid log( String msg, Throwable exception ) {try { LogService log =(LogService) tracker.waitForService(15000);if ( exception == null ) log.log( LogService.LOG_INFO, msg ); else log.log( LogService.LOG_ERROR, msg, exception );return; } catch ( InterruptedException ie ) {} System.out.println( msg + " : " + exception );}

47. 1.2a What Did We Learn? • We now correctly handling the coming and going of services • Using a ServiceTracker simplifies the coding of services that are obtained from the registry • The use of the log is now robust

48. 1.3 Using the Http Service • Register a static HTML page with the local Http Service • What will we learn? • Use the ServiceTracker more extensively • How to register a static HTML page with the Http Service • How to implement the HttpContext

49. 1.3 Publishing a page <<interface>> BundleActivator LogService ServiceTracker Logs messages Activator HttpTracker HttpContext Tracks http servers Registers page <<interface>> Http Service Registers /portal page

50. Provides web access to bundles A powerful servlet runner Supports Servlets Version 2.1 Very simple to export static pages and files (like images) Automatically unregisters servlets when bundle is stopped org.osgi.service.http v1.1Http Service