Monday, March 30, 2009

JBossOSGi - First Release

I am happy to announce the release of JBossOSGi-1.0.0.Alpha3.

You can download it here: jboss-osgi-installer-1.0.0.Alpha3.jar

JBossOSGi-1.0.0.Alpha3 is our first functional release that comes with:

  • Apache Felix integration
  • A specialized JBossOSGi Runtime
  • Integrated Hudson QA
  • IzPack based Installer
  • Bundle hot deployment
  • Management Console
  • Docbook Guides
  • HttpService
  • LogService

You may also what to have a look at the JBossOSGi Diary blog posts

  1. Getting Started
  2. Service Provider Interface
  3. Provided Services
Here are the change log details

Tasks
  • [JBOSGI-29] - Provide Initial Framework SPI
  • [JBOSGI-30] - Integration layer for Apache Felix
  • [JBOSGI-35] - Setup JBoss OSGi download area
  • [JBOSGI-38] - Investigate bundle install/start behaviour with random deployment order
  • [JBOSGI-41] - Verify persistent file storage
  • [JBOSGI-42] - Provide IzPack based Installer
  • [JBOSGI-43] - Hudson QA as integral part of each project release
  • [JBOSGI-44] - Provide bundle hot-deployment on jboss
  • [JBOSGI-45] - Provide minimal JBossOSGi Runtime
  • [JBOSGI-46] - Integrate 3rd party HttpService
  • [JBOSGI-47] - Delegate 3rd party framework logging to jboss logging
  • [JBOSGI-48] - Integrate 3rd party LoggingService
  • [JBOSGI-49] - Integrate 3rd party Management Console
  • [JBOSGI-50] - Provide a docbook guides
  • [JBOSGI-51] - Provide a management view (JMX) on framework and bundles

Enjoy

Friday, March 27, 2009

JBossOSGi - Provided Services

This is the last of a the current series of three blogs on JBossOSGi
  1. Getting Started
  2. Service Provider Interface
  3. Provided Services
Logging Service

The JBossOSGi jboss-osgi-service-logging.jar bundle contains a simple Logging Bridge Service to JBoss Logging. It registers a trivial LogListener with the LogReaderService in case that service is registered with the Framework.

The LogReaderService is part of the standard OSGi Compendium Services. JBossOSGi currently uses the (not yet released) LogService from Apache Felix, which gets deployed as Bundle org.apache.felix.log.jar

The LogListener itself logs messages under the Bundle's symbolic name.

You can therefore change the logging for specific Bundles by setting the respective logging level.

Microcontainer Service

JBossOSGi SPI comes with a service that give access to the JBoss Microcontainer Kernel and the JMX MBeanServer. The service is registered with the Framework under the name

org.jboss.osgi.service.MicrocontainerService

Here is an example of how an OSGi component can register an arbitrary MBean with the MBeanServer.

String sname = MicrocontainerService.class.getName();
ServiceReference sref = context.getServiceReference(sname);
MicrocontainerService service = context.getService(sref);
MBeanServer server = service.getMbeanServer();
server.registerMBean(new Foo(), OBJECT_NAME);


What is there to come?

The intention of this post was to give information on the JBossOSGi Provided Services. This concludes this series of three blogs. I look forward to your feedback on the JBossOSGi User Forum

In my next post I'm hopefully going to write about the JBossOSGi integration for Equniox and Knopflerfish - stay tuned.

JBossOSGi - Service Provider Interface

This is the second of a the current series of three blogs on JBossOSGi
  1. Getting Started
  2. Service Provider Interface
  3. Provided Services
The JBossOSGi Service Provider Interface (SPI) is the integration point between the supported OSGi Frameworks and theJBoss Microcontainer. The configuration defines MC beans for the framework itself and its associated deployers.


The latest version of the JBossOSGi SPI JavaDoc is published online as part of the JBossOSGi Hudson QA Environment.

Bootstrapping JBossOSGi

The OSGiBootstrap provides an OSGiFramework through a OSGiBootstrapProvider.

A OSGiBootstrapProvider is discovered in two stages

  1. Read the bootstrap provider class name from a system property
  2. Read the bootstrap provider class name from a resource file

In both cases the key is the fully qalified name of the org.jboss.osgi.spi.framework.OSGiBootstrapProvider interface.

The following code shows how to get the default OSGiFramework from the OSGiBootstrapProvider.

OSGiBootstrapProvider boot = OSGiBootstrap.getBootstrapProvider();
OSGiFramework fw = boot.getFramework();
Bundle bundle = fw.getSystemBundle();

The OSGiBootstrapProvider can also be configured explicitly. The OSGiFramework is a named object from the configuration.

OSGiBootstrapProvider boot = OSGiBootstrap.getBootstrapProvider();
boot.configure(configURL);

OSGiFramework fw = boot.getFramework("MyOSGiFramework");
Bundle bundle = fw.getSystemBundle();
The JBossOSGi SPI comes with a OSGiBootstrapProvider that uses a JBoss Microcontainer bean configuration.

OSGiBootstrapProvider implementations that read their configurtation from some other source are possible, but currently not part of the JBossOSGi SPI.

Using the SPI from within JBossAS deployed components

If you need access to the OSGi Framework from within an JBossAS deployed component (e.g. servlet, ejb, mbean) you would not bootstrap JBossOSGi through the SPI. Instead, you would inject the already bootstrapped OSGi Framework instance into your component.

Bundle Deployers

JBossOSGi comes with a number of JBoss Microcontainer based deployers. Each deployer takes care of a specific aspect of bundle deployment.
  • BundleMetaDataDeployer - Create BundleMetaData from Manifest Headers
  • BundleRealDeployer - Installs the Bundle into the Framework's SystemContext
  • BundleClassLoaderDeployer - Creates a BundleClassLoader for the deployed Bundle
  • BundleStartStopDeployer - Starts the Bundle when dependencies are resolved
  • BundleManagementDeployer - Register the Bundle as MBean with JMX
BundleMetaDataDeployer

The BundleMetaDataDeployer creates the BundleMetaData from Manifest Headers. If the manifest does not contain a header named Bundle-SymbolicName this deployer does nothing.

BundleRealDeployer

The BundleRealDeployer installs the Bundle into the Framework's SystemContext. Optionally you can configure a list of bundle locations that should be skipped and hence not installed. Typically, these bundles are already installed during Framework startup.

On undeploy the Bundle gets uninstalled from the Framework's SystemContext.

BundleClassLoaderDeployer

The BundleClassLoaderDeployer attaches a ClassLoaderFactory that creates a BundleClassLoader for the deployed Bundle. A BundleClassLoader delegates all classloading concerns to the underlying Bundle.

BundleStartStopDeployer

The BundleStartStopDeployer currently works in two modes:

  • deferredStart (default)
  • simpleStart

In mode deferredStart the Bundle is added to a list of unresolved Bundles, which then get passed on to PackageAdmin.resolveBundles(Bundle[]). The deployer then iterates over the unresolved Bundles and only starts those Bundles that are in state RESOLVED. In this mode Bundles can be deployed in any order and only get started when all their respective dependencies can be resolved.

In mode simpleStart the deployer attempts to start the Bundle regardless of whether its dependencies can get resolved. In case the Bundle has a dependency oin a package that is not yet available, deployment will fail. In this mode Bundles must be deployed in the order required to start them.

The start mode is a configurable property on the Framework's SystemContext.

BundleManagementDeployer

The BundleManagementDeployer registers the Bundle as StandardMBean with JMX. Please see the section on Management View for details.

Management View

JBossOSGi registers the Framework and every deployed Bundle with the JMX MBeanServer.

The ManagedFramework

The ManagedFramework gives you access to the MBean views of the deployed Bundles. It is registerd under the name:

jboss.osgi:service=ManagedFramework
The ManagedBundle

The ManagedBundle gives you access to the MBean views of a deployed Bundle. It is registerd under the name:

jboss.osgi:bundle=[SymbolicName],id=[BundleId]
Accessing the Management Objects

If you work with the JBossOSGi Testsuite you get access to the Managed Objects through the JBossOSGi SPI provided JUnit support package org.jboss.osgi.spi.junit.

If you install JBossOSGi in an already existing JBossAS instance you also get access to the Managed Objects through the JBoss provided JMX Console (http://localhost:8080/jmx-console).



The JMX Console is not part of the JBossOSGi Runtime.

What is there to come?

The intention of this post was to provide information the JBossOSGi SPI.

In my next post I'm going to write about the JBossOSGi Provided Services - stay tuned.

JBossOSGi - Getting Started

This is the first of a the current series of three blogs on JBossOSGi
  1. Getting Started
  2. Service Provider Interface
  3. Provided Services
Installing JBossOSGi

JBossOSGi is distributed as an IzPack installer archive. The installer is available from the JBossOSGi download area.

To run the installer execute the following command:
 java -jar jboss-osgi-installer-1.0.0.Alpha3.jar
The installer first shows a welcome screen



Then you select the installation path for the JBossOSGi distribution. This is the directory where you find the binary build artifacts, the java sources, documentation and the JBossOSGi Runtime.



The installer contains multiple installation packs. Greyed packs are required, others are optional and can be deselected.



  • JBossOSGi Distribution - Documentation, Binary Artifacts and Sources
  • JBossOSGi Runtime - Standalone JBossOSGi Runtime based on JBossAS
  • JBossOSGi Integration - Integration with an existing JBossAS instance

In case you have selected 'JBossOSGi Integration', you will be presented with the choice of supported target containers.

You will then have to point the installer to your existing JBossAS installation.

You can then verify the selected installation options and proceed with the actual installation.

The installer reports its installation progress and finally displays a confirmation screen. You can now optionally generate an "automatic installation script" that you can use when you want to repeat what you have just done without user interaction.

JBossOSGi Runtime

If you selected 'JBossOSGi Runtime' during installation you should see a runtime folder, which contains the JBossOSGi Runtime distribution.

The JBossOSGi Runtime is a customized version of the JBoss Application Server. From that we removed the services that are not absolutely necessary to run the installed OSGi Framework. Consequently, you can start the JBossOSGi Runtime in the same way as you start JBossAS.

[tdiesler@tdvaio runtime]$ bin/run.sh
=========================================================================
JBoss Bootstrap Environment
JBOSS_HOME: /usr/java/jboss-osgi-1.0.0.Alpha3/runtime
...
=========================================================================
[ServerImpl] Starting JBoss (Microcontainer)...
...
[FelixIntegration] OSGi Integration Felix - 1.0.0.Alpha3
[FelixIntegration] Installed bundle: org.osgi.compendium
[FelixIntegration] Installed bundle: org.jboss.osgi.service.logging
[FelixIntegration] Started bundle: org.osgi.compendium
[FelixIntegration] Started bundle: org.jboss.osgi.service.logging
[OSGiDeployer] Installed: jboss-osgi-service-webconsole [3][INSTALLED]
[OSGiDeployer] Installed: org.apache.felix.bundlerepository [4][INSTALLED]
[OSGiDeployer] Installed: org.apache.felix.configadmin [5][INSTALLED]
[OSGiDeployer] Installed: org.apache.felix.http.jetty [6][INSTALLED]
[OSGiDeployer] Installed: org.apache.felix.log [7][INSTALLED]
[OSGiDeployer] Installed: org.apache.felix.metatype [8][INSTALLED]
...
[ServerImpl] JBoss (Microcontainer) [5.0.1.GA] Started in 11s:645ms
Bundle Deployment

Bundle deployment works, as you would probably expect, by dropping your OSGi Bundle into the JBossOSGi Runtime deploy folder.
cp .../test-libs/jbosgi36-bundle.jar .../server/default/deploy

[OSGiDeployer] Installed: jbosgi36 [9][INSTALLED]
[jbosgi36] BundleEvent INSTALLED
[jbosgi36] BundleEvent RESOLVED
[jbosgi36] ServiceEvent REGISTERED
[jbosgi36] BundleEvent STARTED
[BundleStartStopDeployer] Started: jbosgi36 [9][ACTIVE]
Managing installed Bundles

JBossOSGi comes with a simple Web Console, which is currently based on the Apache Felix Web Console project. By default the JBossOSGi Web Console is available at



Hudson QA Environment


Setup the Hudson QA Environment

The JBossOSGi Hudson QA Environment is an integral part of the JBossOSGi code base. It is designed for simplicity because we believe that comprehensive QA will only get done if it is dead simple to do so.

Consequently, you only have to execute two simple ant targets to setup the QA environment that was used to QA the JBossOSGi release that you currently work with.

If in future we should discover a problem with a previous JBossOSGi release, it will be possible to provide a patch and verify that change using the original QA environment for that release.

With every release we test the matrix of supported target containers and JDKs.

Set Hudson Properties

You need to set a few properties, especially these

  • hudson.maven.path
  • hudson.username
  • hudson.password
  • hudson.root
Run Hudson Setup
[tdiesler@tdvaio hudson]$ ant hudson-setup

hudson-setup:
[copy] Copying 2 files to /home/.../hudson/jboss-osgi/apache-tomcat
...
[echo]
[echo] *************************************
[echo] * Hudson setup successfully *
[echo] * ant hudson-start *
[echo] *************************************
[echo]
Run Hudson Start
[tdiesler@tdvaio hudson]$ ant hudson-start

hudson-start:
[echo]
[echo] *************************************
[echo] * Hudson started successfully *
[echo] * http://localhost:8280/hudson *
[echo] *************************************
[echo]
Run Hudson Stop
[tdiesler@tdvaio hudson]$ ant hudson-stop

hudson-stop:
[echo]
[echo] *************************************
[echo] * Hudson stopped successfully *
[echo] * ant hudson-start *
[echo] *************************************
[echo]

What is there to come?

The intention of this blog post was to provide folks with the information to get started with JBossOSGi.

In my next post I'm going to write about the JBossOSGi Service Provider Interface - stay tuned.