IST Amigo Project OSGi framework User’s Guide Public September 2006 Public Project Number : IST-004182 Project Title : Amigo Deliverable Type : Report Deliverable Number : Title of Deliverable : OSGi Amigo framework user’s guide V2 Nature of Deliverable : Software Documentation Internal Document Number : Contractual Delivery Date : Actual Delivery Date : September 2006 Contributing WPs : WP3 Author(s) : Anne GERODOLLE, France Telecom Version : 2 Abstract Keyword list Amigo IST-2004-004182 1/19 September 2006 Public Table of Contents Table of Contents................................................................................................... 2 1 2 Component Overview ..................................................................................... 4 1.1 Introduction .............................................................................................................................. 4 1.2 Changes with regard to the list of OSGi bundles that were planned at Month 18 ............. 4 1.3 log4j Bundle (Library Bundle) ................................................................................................ 5 1.4 kSOAP Bundle (Library Bundle) ........................................................................................... 7 1.5 Amigo Core OSGi Bundle ....................................................................................................... 7 1.6 Amigo kSOAP Export Factory Bundle .................................................................................. 8 1.7 Amigo kSOAP Binding Factory Bundle ............................................................................... 10 1.8 SLP Bundle ............................................................................................................................. 11 Deployment .................................................................................................... 13 2.1 System requirements .............................................................................................................. 13 2.2 Download................................................................................................................................. 13 2.3 Install ....................................................................................................................................... 13 2.3.1 Installing Oscar on a PC ................................................................................................... 13 2.3.2 Installing Oscar on a PDA ................................................................................................ 13 2.4 Configure................................................................................................................................. 14 2.4.1 Edit the lib/bundle.properties file. .................................................................................... 14 2.4.2 Now edit the lib/system.properties file ............................................................................. 14 2.4.3 log4j configuration ........................................................................................................... 14 3 4 2.5 Launching oscar ..................................................................................................................... 15 2.6 Standard Amigo profiles. ....................................................................................................... 15 Quick start ..................................................................................................... 16 3.1 Requirements. ......................................................................................................................... 16 3.2 Configuration .......................................................................................................................... 16 3.3 Running the picture frame server: ....................................................................................... 16 3.4 Running the picture frame client in a different OSGi platform: ....................................... 17 3.5 interacting with a c# client or server .................................................................................... 17 3.6 Managing bundles .................................................................................................................. 17 3.7 Troubleshooting ...................................................................................................................... 17 Appendix ........................................................................................................ 19 4.1 Description of tools/languages provided by component ...................................................... 19 4.2 FAQ ......................................................................................................................................... 19 Amigo IST-2004-004182 2/19 September 2006 Amigo IST-2004-004182 Public 3/19 September 2006 Public 1 Component Overview 1.1 Introduction The OSGi-based programming & deployment framework is composed of a series of OSGi bundles. A subset of these bundles or all these bundles may be installed on each OSGi platform of an Amigo system. The set of bundles installed on an OSGi platform determines the Amigo profile of this platform. The OSGi bundles presented herein may belong to different categories: Encapsulation of OSS libraries developed in another open source project. Then, the license terms should be the same license terms as those of the original project. Original Amigo bundles. The license chosen by France Telecom for these bundles is LGPL. These bundles include an Amigo core bundle (which provides interfaces and basic mechanisms) and specialized bundles that provide adaptation to different protocols. These bundles will be available on the Amigo OSGi bundle repository, which will contain: (i) binary bundles ready for deployment on an OSGi platform, (ii) documentation associated to these bundles, and (iii) source code corresponding to the binary release. The source code will also be available on the Amigo SVN repository. The Amigo OSGi bundle repository is available at http://amigo.gforge.inria.fr/obr/ . 1.2 Changes with regard to the list of OSGi bundles that were planned at Month 18 Priority has been given to interoperability between OSGi/Java and .Net/C# environments. This resulted into the following changes : WS-discovery was delivered at Month 21. A light implementation of the WS-eventing protocol was included in the kSOAP binding factory bundle. The Axis export and binding factories have been released later than foreseen. Unexpected problems were met, and there are still problems with these bundles, see the corresponding section. The UPnP bundle is not yet available. Also, we have simplified the packaging of the kSOAP bundles, by embedding the kSOAP2 library in the kSOAP binding bundle. Some components are used at development time (not at run-time), therefore not available as bundles. Such components are called tools. stubgen and obrgen. Table 1 lists sub-components of the OSGi framework and their dependencies. Component Type Depends on License Availability log4j Ext. bundle Apache Month 20 Amigo core Amigo bundle Log4j LGPL Month 20 Amigo kSOAP Amigo bundle binding factory Amigo core LGPL Month 20 Amigo Amigo core, OSGi HTTP LGPL Month 20 library kSOAP Amigo bundle Amigo IST-2004-004182 4/19 September 2006 Public export factory service, binding Amigo Amigo Axis Amigo bundle export factory Amigo core, HTTP service Amigo Axis Amigo bundle binding factory Amigo core, Axis OSGi, LGPL Month 24 (prev. Month 22) Amigo adapter SLP Amigo bundle Log4j, Amigo core LGPL Month 20 Amigo adapter UPnP Amigo bundle Axis kSOAP OSGi LGPL Month 24 (prev. Month 22) Log4j, Amigo core, OSGi LGPL UPnP base driver Month 26 (prev. Month 24) Amigo dynamc Amigo bundle stub generator Log4j, Amigo core, LGPL Month (new) Amigo WS-discovery adapter Amigo bundle Log4j, Amigo core, kSOAP LGPL Month 20 (prev. Month 24) Amigo Service Binder Amigo bundle Log4j, Amigo core LGPL Month 27 Amigo Semantic Amigo bundle adaptation bundles Log4j, Amigo core LGPL Month 30 stub tool LGPL Month (new) 24 obr repository tool generator LGPL Month (new) 24 static generator 24 Table 1: sub-components of the OSGi framework 1.3 log4j Bundle (Library Bundle) Provider Library provided by Apache / OSGi encapsulation by France Telecom Introduction This bundle encapsulates the log4j library, an open flexible logging system for Java applications. log4j is developed within the Apache project (http://logging.apache.org/log4j). Development status Done: encapsulation of log4j 1.2.13 To be provided M21: encapsulation of log4j mini (to be used on constrained devices) Amigo IST-2004-004182 5/19 September 2006 Public Intended audience This is general purpose software for any Java developer. License Apache license Language Java Environment (set-up) info needed if you want to run this sw (service) Hardware / OS: Any OS supporting Java personal profile or J2SE Platform Java (personal profile or J2SE), OSGi Tools None Files log4j_bu.jar contains the log4j bundle test-log4j.jar contains a bundle that uses the log4j bundle Documents For general documentation see http://logging.apache.org. The OSGi bundle will be provided with an example of use. Tasks First release Month 18 for Amigo partners Public release Month 20 Bugs None so far Patches None so far Amigo IST-2004-004182 6/19 September 2006 Public 1.4 kSOAP Bundle (Library Bundle) This bundle has been suppressed as from OSGi Amigo release v1 and further v2 : the kSOAP and kxml bundles are now embedded in the kSOAP binding factory bundle. 1.5 Amigo Core OSGi Bundle Provider France Telecom Introduction This bundle provides the Java interfaces and core classes that form the Amigo programming framework core: interfaces ExportFactory, BindingFactory, AmigoLdapLookup… Remark: This bundle provides basic mechanisms for communication and service discovery, but is not linked with any protocol. It should be deployed together with implementing bundles related to communication protocols (binding factories and/or export factories) or service discovery protocols. Development status available Intended audience Java developers that want to expose Java objects as remote services; Java developers that want to access to remote services; Java developers that want to asynchronously send or receive events Java developers that want to write an adapter for a given technology. License LGPL Language Java Environment (set-up) info needed if you want to run this sw (service) Hardware / OS: Any OS supporting Java personal profile or J2SE Platform Java (personal profile or J2SE), OSGi Tools None Amigo IST-2004-004182 7/19 September 2006 Public Files The bundle appears on the bundle repository under a “bundle name” indicated in brackets. amigo_core.jar: bundle that amigo_core); hello_server.jar: test bundle that exports a simple Hello service (bundle name amigo_test_hello_server); hello_client.jar: test bundle that uses a Hello service using a well-known endpoint (bundle name amigo_test_hello_client); hello_lookup_client: test bundle that discovers the available Hello services and uses the first discovered (bundle name amigo_test_hello_lookup_client). test_pictureframe_server.jar: test bundle that provides a “picture frame” (bundle name amigo_test_pictureFrame_server) as an amigo service. test_pictureFrame_client.jar: test bundle for the amigo test picture frame server: this displays a graphical interface to choose an image from available images on the client’ file system to be displayed by the “picture frame” server (bundle name amigo_test_pictureFrame_client). provides the core interfaces and classes (bundle name Documents Java documentation, tutorial, http://amigo.gforge.inria.fr/obr/ developer’s and user’s guide available on Tasks Initial version Month 18 for Amigo partners Public release Month 20 Bugs None so far Changes v1 : added API for eventing (subscription manager, event source, event sink) v2 : modified the “getSpecificStub” interface. Definition of the “stub generator” interface. Patches None so far 1.6 Amigo kSOAP Export Factory Bundle Provider France Telecom Introduction Amigo IST-2004-004182 8/19 September 2006 Public This bundle allows making a Java object available through the SOAP protocol. It provides a local OSGi service that implements the ExportFactory interface. The choice of the kSOAP library allows this bundle to be deployed on constrained devices. Development status Initial release Month 18 Intended audience Network administrators who want to use HTTP/SOAP as the base communication protocol should deploy this bundle on every OSGi platform that will provide remote services using the Amigo core API. This bundle is not used at development time. License LGPL Language Java Environment (set-up) info needed if you want to run this sw (service) Hardware / OS: Any OS supporting Java personal profile or J2SE Software: kSOAP bundle, log4j bundle, HTTP service, servlet Platform Java (personal profile or J2SE), OSGi Tools None Files amigo_ksoap_export.jar Documents Java documentation Tasks Initial version Month 18 for Amigo partners Public release Month 20 Enhancements foreseen: WSDL generation Amigo IST-2004-004182 9/19 September 2006 Public Bugs None so far Patches None so far 1.7 Amigo kSOAP Binding Factory Bundle Provider France Telecom Introduction This bundle allows building a stub to a remote object accessible through the SOAP protocol. It provides a local OSGi service that implements the BindingFactory interface. This bundle encapsulates the kSOAP2 and kxml2 libraries, which allow writing XML- or SOAPrelated applications for any Java target (Midp, personal profile, J2SE). kSOAP2 is developed inside the kObject project (http://kobject.sourceforge.net); kXLM2 is developed within the kXML project (http://kxml.sourceforge.net/). Development status Initial release Month 18. Intended audience Network administrators who want to use HTTP/SOAP as the base communication protocol should deploy this bundle on every OSGi platform that will access to remote services using the Amigo core API. This bundle is not used at development time. License LGPL Language Java Environment (set-up) info needed if you want to run this sw (service) Hardware / OS: Any OS supporting Java personal profile or J2SE Software: kSOAP bundle, log4j bundle Amigo IST-2004-004182 10/19 September 2006 Public Platform Java (personal profile or J2SE), OSGi Tools None Files amigo_ksoap_binding.jar Documents Java documentation Tasks Initial version Month 18 for Amigo partners Public release Month 20 Bugs None so far Changes v1 : modified the ksoap library so as to handle “reasonably complex” types Patches None so far 1.8 SLP Bundle Provider France Telecom Introduction This bundle provides an implementation of AmigoLdapLookup based on SLP (Service Location Protocol). Development status Initial version based on mesh SLP (Columbia University) under test. Original library can be found at http://mslp.sourceforge.net/ . Amigo IST-2004-004182 11/19 September 2006 Public Intended audience Network administrators who want to use SLP as the base protocol for service discovery in Amigo may deploy this bundle on every OSGi platform that will access to SLP using the Amigo core API. This bundle is not used at development time. License LGPL Language Java Environment (set-up) info needed if you want to run this sw (service) Hardware / OS: Any OS supporting Java J2SE or personal profile Platform Java (personal profile or J2SE), OSGi Tools None Files amigo_meshslp.jar Documents Java documentation Tasks Initial version Month 18 for Amigo partners Public release Month 20 Bugs None so far Patches None so far Amigo IST-2004-004182 12/19 September 2006 Public 2 Deployment 2.1 System requirements Any system with a Java runtime (at least personal profile) 2.2 Download Amigo bundles should be compatible with any OSGi R3 compliant platform. Amigo bundles have been tested against Oscar 1.0.5. You may download a pre-configured Oscar platform from http://amigo.gforge.inria.fr/obr/tools/oscar_j2se.zip . 2.3 Install 2.3.1 Installing Oscar on a PC After downloading Oscar_j2se.zip from http://amigo.gforge.inria.fr/obr/tools/oscar_j2se.zip , unzip it in any directory. 2.3.2 Installing Oscar on a PDA To install Oscar on a Linux PDA: you may use the ordinary process, however you may prefer to obtain directly a “tiny shell” adapted to small screen sizes. To that purpose, just download and unpack http://amigo.gforge.inria.fr/obr/tools/oscar_pda.zip . Then make the necessary changes (see configuration) to use your http proxy. Installing Oscar on Windows CE is a little more tricky, but not impossible. One problem is that the notion of “current directory” when you launch a program seems inexistent on this system. Thus, you’d rather use absolute paths. Another problem is that there is nothing like bat files, so that you have to put commands in “shortcuts”, which will contain something like a command line limited to 80 characters. Nevertheless, here are some instructions to help you through this process: First thing is to install a Java runtime with personal profile. The IBM J9 works fine; to install it visit http://awareness.ics.uci.edu/~rsilvafi/pocketPC/ . Then you have to copy oscar on your PDA. To this purpose: download and unpack http://amigo.gforge.inria.fr/obr/tools/oscar_pocket_pc.zip Unzip the file. Edit the lib/system.properties to set your proxy properties if necessary. Using Microsoft active sync, copy all sub-folders to your pda root folder. Two shortcuts are created in Oscar: if you use “amigo.bat”, you will launch an oscar platform with the default “amigo” profile. If you use “oscar.bat”, you will be prompted for the profile name in the console. Amigo IST-2004-004182 13/19 September 2006 Public 2.4 Configure Go to the installation directory of Oscar. It contains 3 folders, lib, doc and bundle. The lib folder contains both libraries and configuration files; the doc folder contains Oscar’s documentation ; the bundle folder contains bundles used in the Oscar’s initialization phase. If you have downloaded a pre-configured Oscar, it should not be necessary to change these files, but we shall have a look to these files anyway. 2.4.1 Edit the lib/bundle.properties file. It defines the location of the bundle repository is, and the port that the OSGi platform will try to use for http services. For bundles developed outside Amigo, we use a copy of the standard Oscar bundle repository. This is because two bundles have been modified for Amigo’s project purposes : the UPnP base driver, and the HTTP service bundle. oscar.repository.url= \ http://amigo.gforge.inria.fr/obr/tools/oscar-repository.xml \ http://amigo.gforge.inria.fr/obr/v2/repository.xml # the port on which the http server will listen org.osgi.service.http.port=8080 2.4.2 Now edit the lib/system.properties file # list of mandatory bundles that must be started when oscar is launched oscar.auto.start.1=file:bundle/shell.jar file:bundle/tablelayout.jar \ file:bundle/shellgui.jar file:bundle/shellplugin.jar \ file:bundle/bundlerepository.jar # if you have to use a http proxy here is where to put the properties #http.proxySet=true #http.proxyHost=myProxyHost #http.proxyPort=myProxyPort #http.nonProxyHosts=”mymachine|*.mydomain” If you are behind a firewall, you will have to uncomment the lines beginning with http and set your own proxy parameters. We could also change the oscar.auto.start property, for example to automatically launch some amigo bundles when starting oscar, or to suppress the graphical console. See the oscar_pda installation. 2.4.3 log4j configuration Amigo core bundles use log4j for logging. You need to configure log4j. For the sake of this tutorial, we will log on the console. Have a look on the oscar.bat or oscar.sh file : java -Dlog4j.configuration=file:lib/log4jbasic.properties -jar lib\oscar.jar It refers to a file named log4jbasic.properties that contains the log4j configuration. You may have a look to this file. log4j offers many possibilities that we will not cover in this tutorial. Amigo IST-2004-004182 14/19 September 2006 Public 2.5 Launching oscar oscar can be launched using the amigo.bat or amigo.sh script, depending on which Operating system you are running. This launches Oscar with a “profile” named amigo. A “profile” is associated to a cache folder, so that if you stop oscar and start it later with the same profile, memory will be kept of which bundles were installed and which bundles were started. This is documented on http://oscar.objectweb.org . The profile must be specified in the oscar.cache.profile property. If you are a developer and you want to start two profiles on the same machine (for testing purposes) you may either create several script files (each associated to a cache) or use the oscar.bat (oscar.sh on Linux) script. When launching the latter, Oscar prompts you for a profile name. Once you have launched oscar, you may deploy a set of bundles which will define the “Amigo profile” of your platform: it may be a server profile, or a client profile, with or without Context management, etc. Chapter 3 shows how to interactively create and run two simple “server” and “client” profiles. You may also create the profiles statically by modifying the property oscar.auto.start.1 in bundle.properties so that some Amigo bundles are automatically launched at start-up. However, although an Amigo profile (a list of bundles) can be deployed on any OSGi R3 compliant platform, the way to define profiles and start automatically bundles depends on the OSGi platform. Please refer to the documentation of the platform you are using. 2.6 Standard Amigo profiles. A standard client profile contains bundles for placing ksoap calls and discovering services, that is: amigo_core log4j service binder amigo_ksoap_binding amigo_wsdiscovery A standard server profile should contain also bundles for answering ksoap calls : amigo_core log4j service binder amigo_ksoap_binding http service servlet amigo_ksoap_export amigo_wsdiscovery Amigo IST-2004-004182 15/19 September 2006 Public 3 Quick start This section explains how to deploy the Amigo “picture frame” example client-server on OSGi. You may deploy the client and the server on two different OSGi platforms or both on the same OSGi platform. The server opens a virtual picture frame (a window) on the target platform – PC or PDA, and announces its services on the network. The client presents a graphical interface that allows discovering all available “picture frame” servers on the network. After selecting one of the servers, the user can select a picture file on the client’s file system and display it on the server’s picture frame. OSGi Clients may discover –and interact with - .Net or OSGi servers. The same applies to .Net clients. Launching a picture frame client or server on .Net is described in the EMIC documentation. 3.1 Requirements. A Java Run time (at least Personal Profile) A OSGi platform, e.g. Oscar 1.0.5 http://oscar.objectweb.org 3.2 Configuration Refer to previous section 2, Deployment, to install and configure a OSGi platform. 3.3 Running the picture frame server: Launch oscar (use oscar.bat or oscar.sh, depending on which platform you are). On Linux, for convenience you may type “chmod +x oscar.sh” . Oscar prompts you for a “profile”. Enter “server”. Explanation: a “profile” is associated to a cache folder, so if you stop oscar and start it later with the same profile, memory will be kept of which bundles were installed and which bundles were started. To avoid being prompted each time you launch oscar, you may modify the command (see amigo.bat or amigo.sh). This is documented on http://oscar.objectweb.org . You should see a window called « Oscar Gui Shell ». A bundle list is displayed, with some bundles already installed. On the left you can see 3 buttons (Bundle List, Shell and OBR). These buttons allow navigating between 3 different screens, as we shall see later on. Click on “OBR”. You should see the list of available bundles. Choose “amigo_test_pictureframe_server” and click on “start all”. On the left, click on “Bundle List”. You can see that several bundles have been added to the list: the amigo_test_pictureframe_server bundle, but also the amigo_core, log4j and servicebinder bundles. This is because the amigo_test_pictureframe_server you just installed requires classes that are provided by these bundles. Click again on “OBR”. Start now “amigo_ksoap_export” and “amigo_ws_discovery”. If everything went well, the picture frame server is now ready. Explanation: the picture frame requires that implementations of “export factory” and “AmigoLdapLookup” are available on the OSGi platform. The bundles we have just installed provide implementations of these interfaces. Amigo IST-2004-004182 16/19 September 2006 Public 3.4 Running the picture frame client in a different OSGi platform: Launch oscar (using oscar.bat or oscar.sh). When Oscar prompts you for a “profile”, enter “client”. Click on “OBR”. Choose “amigo_test_pictureframe_client” and click on “start all”. Choose “amigo_ksoap_binding” and click on “start all”. Choose “amigo_wsdiscovery” and click on “start all”. If everything went well, you should see a small window called “picture frame client”. Click on “discovery” . You should see a list of available picture frames. Choose one. A file selector should open. Select an image file. The image should be sent to the server and displayed on it. Congratulations: you have run your first Amigo application. If not, go to the troubleshooting part. 3.5 interacting with a c# client or server Download the picture frame project from EMIC http://amigo.gforge.inria.fr/home/components/wp3/NET_Framework/download/component.zip. Build the picture frame client and server. Launch the EMIC server. Your client should now be able to discover and use it. Inversely, if you launch the EMIC picture frame client, it should be able to discover your server and use it. 3.6 Managing bundles Close the picture frame client window: you should see in the client’s gui shell (in the bundle list screen) that the client is no more “active”. If you select it and click on “start”, the window shows again and the bundle state returns to “active”. Return to the osgi gui shell of the server. In “OBR” start a “http Shell”. Now open a Web browser and go to the http://<your_host>:8080/admin url (remember we decided to run the http server of oscar on the 8080 port). You can now manage the platform from a web browser (useful if OSGi is running on a pocket PC or a device without a display). In the Web browser Oscar GUI, click on “Shell”. Try the different commands (you have a list of commands by typing « help »). Finally, you may stop the picture frame server and picture frame client OSGi platforms by typing “shutdown” in the shell window. 3.7 Troubleshooting If you encountered problems running this example: 1- Oscar Shell Gui did not show. Maybe Oscar is not configured to show a shell gui. Edit the lib/system.properties file. Fill in the oscar.auto.start.1 property as follows: Amigo IST-2004-004182 17/19 September 2006 Public oscar.auto.start.1=file:bundle/shell.jar file:bundle/tablelayout.jar \ file:bundle/shellgui.jar file:bundle/shellplugin.jar \ file:bundle/bundlerepository.jar file:bundle/shelltui.jar 2- The shell gui shows, but when I click on OBR nothing happens. Have a look to the console. If a « timeout » exception is displayed, your proxy parameters must be wrong or you are not connected to the Internet. 3- When I click on OBR I do not see the Amigo bundles. Check the contents of oscar.repository.url in lib/bundle.properties . 4- The picture frame does not show. Maybe the HTTP port was busy. Have a look to the console. Is there a message like “Address already in use? Then you have to choose a different port for the http service. Stop Oscar (choose “Shell” in the GUI then type “shutdown”). If you are on a Linux system, choose a port number above 1024. Check that this port number is available using for example “telnet localhost 8080”. Set the http port to this value (see the “configuration” section). If you run two OSGi platforms on the same machine, they cannot use the same port ! See “how can launch two OSGi platforms with HTTP service on the same computer ? “ 5- how can launch two OSGi platforms with HTTP service on the same computer ? create a copy of bundle.properties (call it for example mybundle.properties) which specifies a different http port. Create a copy of oscar.bat (or oscar.sh) where you specify the following jvm argument : -Doscar.bundle.properties=lib/mybundle.properties 6- How can I monitor the client platform using http ? If you have 2 Oscar platforms on the same host, and you want to monitor both of them using http, you should specify a different http port for the http service. See previous question “how can launch two OSGi platforms with HTTP service on the same computer ?” Amigo IST-2004-004182 18/19 September 2006 Public 4 Appendix 4.1 Description of tools/languages provided by component n.a. 4.2 FAQ Amigo IST-2004-004182 19/19