JBoss.orgCommunity Documentation

Chapter 2. Getting Started

2.1. Download the Distribution
2.2. Running the Installer
2.3. Starting the Runtime
2.4. Provided Examples
2.5. Bundle Deployment
2.6. Managing installed Bundles
2.7. Hudson QA Environment

This chapter takes you through the first steps of getting JBoss OSGi and provides the initial pointers to get up and running.

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

To run the installer execute the following command:

    java -jar jboss-osgi-installer-1.0.0.Beta4.jar
    

The installer first shows a welcome screen

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

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

Next, you will be presented with the choice of supported OSGi Frameworks.

In case you have selected 'JBoss OSGi 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.

Supported JBossAS versions

The Microcontainer based OSGi Framework is only supported on JBoss-5.2.0 and above.

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.

If you selected JBoss OSGi Runtime during installation you should see a runtime folder, which contains the JBoss OSGi Runtime distribution. The JBoss OSGi Runtime is an OSGi container onto which services and applications can be deployed.

The layout of the JBoss OSGi Runtime after installation is similar to what you know from JBossAS.

You can start the Runtime by running bin/run.sh. The supported command line options are:

  • -c (--server-name) - The runtime profile to start. The default is the 'default' profile.
  • -b (--bind-address) - The network address various services can bind to. The default is 'localhost'
    [tdiesler@tddell runtime]$ bin/run.sh
    =========================================================================
    
      JBoss OSGi Bootstrap Environment
    
      OSGI_HOME: /home/tdiesler/jboss-osgi-1.0.0.Beta4/runtime
    
      JAVA: /usr/java/jdk1.6/bin/java
    
      JAVA_OPTS: ...
    
    =========================================================================
    
    15:36:52,683 INFO  [OSGiBundleManager] JBossOSGi Framework - 1.0.0.Alpha1
    15:36:53,161 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{osgi.cmpn:4.2.0.200908310645}
    15:36:53,280 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{org.apache.felix.log:1.0.0}
    15:36:53,403 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{jboss-osgi-common:1.0.2.SNAPSHOT}
    15:36:53,442 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{jboss-osgi-hotdeploy:1.0.2.SNAPSHOT}
    15:36:54,431 INFO  [jboss-osgi-hotdeploy] Start DeploymentScanner: [scandir=.../server/default/deploy,interval=2000ms]
    15:36:54,462 INFO  [OSGiBootstrap] JBossOSGi Runtime booted in 1.773sec
    ...
    15:36:54,515 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{jboss-osgi-jndi:1.0.1}
    15:36:54,551 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{jboss-osgi-jmx:1.0.1}
    15:36:54,783 INFO  [FrameworkEventsPluginImpl] Bundle INSTALLED: Bundle{jboss-osgi-common-core:2.2.13.GA}
    ...
    15:36:55,353 INFO  [jboss-osgi-jndi] JNDI started: JNP=localhost:1099, RMI=localhost:1098
    15:36:55,687 INFO  [jboss-osgi-jmx] MBeanServerConnection bound to: jmx/invoker/RMIAdaptor
    ...
    15:36:57,705 INFO  [OSGiBootstrap] JBossOSGi Runtime started in 3.021sec
    

JBoss OSGi comes with a number of examples that you can build and deploy. Each example deployment is verified by an accompaning test case

Bundle deployment works, as you would probably expect, by dropping your OSGi Bundle into the JBoss OSGi Runtime deploy folder.

    [tdiesler@tdvaio testsuite]$ cp .../test-libs/example/example-http.jar .../runtime/server/web/deploy
    ...
    13:59:38,284 INFO  [BundleRealDeployer] Installed: example-http [9]
    13:59:38,289 INFO  [example-http] BundleEvent INSTALLED
    13:59:38,297 INFO  [example-http] BundleEvent RESOLVED
    13:59:38,304 INFO  [example-http] ServiceEvent REGISTERED
    13:59:38,306 INFO  [BundleStartStopDeployer] Started: example-http [9]
    13:59:38,306 INFO  [example-http] BundleEvent STARTED
    

JBoss OSGi comes with a simple Web Console, which is currently based on the Apache Felix Web Console project. The JBoss OSGi Web Console is included in the runtime profiles 'web' or 'all'. After startup you can point your browser to http://localhost:8090/jboss-osgi.

The Web Console can also be used to install, start, stop and uninstall bundles.

Setup the Hudson QA Environment

The JBoss OSGi Hudson QA Environment is an integral part of the JBoss OSGi 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 JBoss OSGi release that you currently work with.

If in future we should discover a problem with a previous JBoss OSGi 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, frameworks and JDKs.

Set Hudson Properties

You need to set a few properties, especially these

  • hudson.maven.path
  • hudson.username
  • hudson.password
  • hudson.root
    cd build/hudson
    cp ant.properties.example ant.properties
    vi ant.properties
    
    # The JBoss settings
    jboss.server.instance=default
    jboss.bind.address=127.0.0.1
    
    # JDK settings
    java.home.jdk15=/usr/java/jdk1.5.0_17
    java.home.jdk16=/usr/java/jdk1.6.0_11
    
    # Hudson QA Environment
    hudson.username=chageme
    hudson.password=chageme
    
    hudson.maven.path=/usr/java/apache-maven-2.0.9
    
    hudson.root=/home/tdiesler/workspace/hudson/jboss-osgi
    
    hudson.maven.profile=$HUDSONDIR/profiles.xml.local.qa
    
    hudson.host=jbpm.dyndns.org
    hudson.admin.port=8250
    hudson.http.port=8280
    
    #hudson.jboss501.zip=file:///home/tdiesler/Download/java/jboss/jboss-5.0.1.GA.zip
    
    hudson.mail.recipients=
    hudson.smtp.host=localhost
    
    # Hudson (1.290)
    apache-tomcat=5.5.20
    sun-hudson=2402/128862
    
Run Hudson Setup
    [tdiesler@tdvaio hudson]$ ant hudson-setup
    Buildfile: build.xml
    
    init:
         [echo] V1.0.0.Beta4
    
    init-hudson:
         [echo] 
         [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
         [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
         [echo] 
    
    ...
    
    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
    Buildfile: build.xml
    
    init:
         [echo] V1.0.0.Beta4
    
    init-hudson:
         [echo] 
         [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
         [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
         [echo] 
    
    hudson-start:
         [echo] 
         [echo] *************************************
         [echo] * Hudson started successfully       *
         [echo] * http://localhost:8280/hudson      *
         [echo] *************************************
         [echo] 
    
    BUILD SUCCESSFUL
    
Run Hudson Stop
    [tdiesler@tdvaio hudson]$ ant hudson-stop
    Buildfile: build.xml
    
    init:
         [echo] V1.0.0.Beta4
    
    init-hudson:
         [echo] 
         [echo] hudson.root = /home/tdiesler/workspace/hudson/jboss-osgi
         [echo] hudson.home = /home/tdiesler/workspace/hudson/jboss-osgi/hudson-home
         [echo] 
    
    hudson-stop:
         [echo] 
         [echo] *************************************
         [echo] * Hudson stopped successfully       *
         [echo] * ant hudson-start                  *
         [echo] *************************************
         [echo] 
    
    BUILD SUCCESSFUL