This is my first tutorial published on this blog. I hope you'll find it helpful and interesting.
In this tutorial you will:
- Learn where to find and how to build and install an OSGi Deployment Admin Service implementation (well, at least partial implementation, but I guess you are welcome to contibute to it)
- Get to know the structure of a standard "Deployment Package"
- Learn how to use the Felix Web Console together with Deployment Admin to install and run a full OSGi based application (consisting of multiple bundles)
I assume that you are familiar with OSGi Service Compendium Release 4 specification (particularly section 114) so I will simply skip the introduction part to save myself some typing.
In this tutorial I will concentrate on one of the most essential responsibilities of a Deployment Admin Service. As described in Service Compendium the Deployment Admin
"provides a Deployment Package concept to install and uninstall bundles and related resources on an OSGi Service Platform as an atomic unit"Isn't it cool? We can package all our bundles (together with their configuration and permission information) into a single archive and then deploy it at once! Great!
Let's check it all out then.
Step 1: Starting the OSGi Container
In this tutorial I will use "
Equinox 3.4". On the downloads page select the "eclipse-equinox-3.4.zip" and save it on your hard drive. While you're on the equinox downloads web site, take a look at the "Add-on Bundles"... do you see Deployment Admin there? No. Me neither :-) But don't worry, we will take care about it later.
Unpack Equinox (stuff inside the "eclipse" directory) to some meaningful directory (e.g. /opt/equinox or C:\Software\equinox). After you are done, cd to the instalation folder and start the container by issuing this command:
$ java -jar plugins/org.eclipse.osgi_3.4.0.v20080605-1900.jar -console
Great! It works. Now we need to customize the initial configuration a little bit to make sure that all required services are there before we begin with Deployment Admin and Felix Web Console.
Exit OSGi console (type "exit"). Go to you equinox/plugins/configuration directory. Create new file called "config.ini" and fill it with the following content:
osgi.bundles=org.eclipse.equinox.common_3.4.0.v20080421-2006@2:start,\
org.eclipse.osgi.util_3.1.300.v20080303.jar@2:start,\
org.eclipse.osgi.services_3.1.200.v20071203@2:start,\
org.eclipse.equinox.event_1.1.0.v20080225@2:start,\
org.eclipse.equinox.util_1.0.0.v20080414@2:start,\
org.eclipse.equinox.cm_1.0.0.v20080509-1800@2:start,\
org.eclipse.equinox.ds_1.0.0.v20080427-0830@2:start,\
org.eclipse.equinox.log_1.1.0.v20080414@2:start,\
javax.servlet_2.4.0.v200806031604@2:start,\
org.eclipse.equinox.http.servlet_1.0.100.v20080427-0830@2:start,\
org.apache.commons.logging_1.0.4.v20080605-1930@2:start,\
org.mortbay.jetty_5.1.14.v200806031611@2:start,\
org.eclipse.equinox.http.jetty_1.1.0.v20080425@2:start
Start the equinox again and type "ss" for status information. You should see this:
Great. Now lets play with the new stuff...
Step 2: Getting the Deployment Agent Implementation
I've spend some time googling to actually find a "half-functional" implementation of this service. I don't know, maybe the implementors thought that this service is kind of unimportant, but I find it quite useful... whatever. The only existing implementation (that I know to this point of time) comes from Apache Felix project. It is however not available yet in form of a stable, binary distribution. To use it you will need to download the sources and build it yourself. The good part of the story is that Apache guys used Maven as their "build tool" so getting the jar is just the matter of typing one simple command.
Here's what you do:
- Get the sources from the Felix SVN repository
- Build the project with "mvn clean install"
- Copy the newly created jars (org.apache.felix.deploymentadmin-0.9.0-SNAPSHOT.jar, and org.apache.felix.deployment.rp.autoconf-0.1.0-SNAPSHOT.jar) to your equinox/plugins directory.
- From the Felix downloads website get the Dependency Manager (version 2.0.1 and copy it to the equinox/plugins directory (required by Deployment Admin Service)
- Update the equinox/plugins/configuration/config.ini file adding the new bundles to the end of the list
...
org.apache.felix.dependencymanager-2.0.1@2:start,\
org.apache.felix.deployment.rp.autoconf-0.1.0-SNAPSHOT@2:start,\
org.apache.felix.deploymentadmin-0.9.0-SNAPSHOT@2:start
Start Equinox. Type "ss". You should see all services as "ACTIVE".
Step 3: Creating the Deployment Package
Nice. The Deployment Admin seems to run just fine. It would be good to check out how it deals with a standard "Deployment Package".
What is a deployment package? Well, according to spec -
"A Deployment Package is a set of related resources that need to be managed
as a unit rather than individual pieces. For example, a Deployment Package
can contain both a bundle and its configuration data. The resources of a
Deployment Package are tightly coupled to the Deployment Package and
cannot be shared with other Deployment Packages."Let's create one then, a really simple one. First, lets take a look at the basic structure of a
*.dp file (MIME type: application/vnd.osgi.dp).
deploymentpackage-0.0.1.dp
|
- org.nowaqblog.bundle1-0.0.1.jar
- org.nowaqblog.bundle2-0.0.1.jar
- META-INF
|- MANIFEST.MF
As you can see our deployment package is a simple jar/zip file (having "dp" extension) which consists of two bundles and a MANIFEST.MF file. The bundles are the complete application that we want to deploy using Deployment Agent. The MANIFEST.MF consists of specialy defined sections. The "global section" and multiple "name sections". The content of these sections is well described in OSGi Sevice Compendium (114.3.3).
For the purpose of this tutorial I created a simple deployment package MANIFEST.MF file like this:
Manifest-Version: 1.0
Created-By: 1.6.0_13 (Sun Microsystems Inc.)
Created-At: 1254918423406
DeploymentPackage-ManifestVersion: 1
Content-Type: application/vnd.osgi.dp
DeploymentPackage-SymbolicName: org.nowaqblog.deploymnetpackage
DeploymentPackage-Version: 0.0.1
DeploymentPackage-Copyright: Nowaq (c) 2009
DeploymentPackage-ContactAddress: mailto:your.email@host
DeploymentPackage-DocURL: http://host/doc
Name: org.nowaqblog.bundle1-0.0.1.jar
Bundle-SymbolicName: org.nowaqblog.bundle1
Bundle-Version: 0.0.1
Name: org.nowaqblog.bundle2-0.0.1.jar
Bundle-SymbolicName: org.nowaqblog.bundle2
Bundle-Version: 0.0.1
So, your job is simply to package all the bundles being the part of your application into dp file and add appropriate description in the MANIFEST.MF file. Simple, isn't it?
Step 4: Installing deployment packages via Deployment Admin Web UI (Felix Web Console)
Ok. Now we have all that we need. The deployment admin and the deployment package are ready to be used. How to do it then? Well, two options come to my mind. We could either extend the Equinox Management Console with a new command or use the Felix Web Console and deploy our package using web interface. You may find the first approach cooler (you learn how to use Deployment Agent API), but for the sake of simplicity I will stick with the second approach in this tutorial.
First we need the web console installed. Go ahead and download it from Felix web site (
http://mirror.uoregon.edu/apache/felix/org.apache.felix.webconsole-1.2.10.jar).
Add this new bundle to your equinox startup configuration. (Add new entry in the config.ini file.)
...
org.apache.felix.webconsole-1.2.10@2:start
Start equinox and type "ss". All bundles should be "ACTIVE".
You may now check out the Felix Web Console at
http://localhost/system/console. You will need to authenticate with "admin/admin". Play around a bit and go to the "Deployment packages" tab. This is the one of particular interest for us.
Step 5: Deploying the application to the OSGi Container
This is the easiest part of the story :-) In the Deployment Admn view of the Felix Web Management Console browse for your "dp" file and click on Install/Update button. Your package should deploy in a few seconds. The web interface will provide you will all the information you need.
Check out equinox console. The packages should be there indicating the "ACTIVE" state. Yeah! You just deployed your first "Deployment Package" using a "Deployment Admin Service". Congratulations!
