OSGi Framework Configuration and Management

This chapter describes how to configure and use the OSGi framework with the JEUS OSGi module.

1. Overview

To execute an application written according to the OSGi specifications and composed of bundles, the OSGi framework is necessary. The OSGi framework is a fundamental component of OSGi technology, responsible for deploying and managing bundles, handling dependencies between bundles, and facilitating the registration and management of services through the OSGi service registry.

The JEUS OSGi module facilitates the setup of an OSGi environment for the user, by automatically creating instances of the OSGi framework during the initialization process when the JEUS server starts, and by installing the pre-configured bundles. These tasks are performed through server configuration. The user can execute the related tasks by using jeusadmin, a console-based management tool.

JEUS uses Apache Felix to implement the OSGi framework. For more information about Apache Felix, refer to Apache Felix Official Documentation.

2. OSGi Framework Configuration Items

OSGi framework configuration items are as follows.

The configuration items for OSGi on JEUS do not support dynamic configuration. To change the configuration of a running server, a server restart is necessary.

  • Name

    Specifies the unique name of the OSGi framework.

  • JNDI Export Name

    Specifies the name of JNDI to which OSGi framework objects are registered. If not specified, the framework name specified in 'Name' is used as the default JNDI name. When a user application directly accesses the OSGi framework, it can use the framework objects registered in JNDI by performing a JNDI lookup. The OSGi framework objects registered in JNDI are only valid within the server environment, and remote JNDI lookup is not supported.

  • Target Servers

    Specifies the server to use the OSGi framework.

  • Framework Configuration Properties

    Specifies the configuration values to be applied when creating and initializing the OSGi framework. Each property is set as a key-value pair. You can use both pre-defined properties specified in the OSGi specifications and pre-defined values in Apache Felix framework. Additionally you can define application-specific configuration properties. For more information about properties defined by the OSGi specifications, refer to OSGi Core Specification. To lean about properties defined by Apache Felix used in JEUS, refer to Apache Felix Framework Configuration Properties

    If the user does not specify the properties, default values are configured by the JEUS OSGi as follows.

    Property Value

    felix.startlevel.bundle

    30

    org.osgi.framework.bundle.parent

    framework

    org.osgi.framework.startlevel.beginning

    100

    org.osgi.framework.storage

    SERVER_HOME/.workspace/osgi/FRAMEWORK_NAME

  • Configuration items for Initial Bundles Directory

    The JEUS OSGi module provides configuration items to specify the initial bundles directory and control its operation. If the initial bundles directory is specified for use, the JEUS OSGi module completes the initialization process of the framework and checks the designated location. It treats the JAR files in the directory as bundles and installs them in the framework.

    JEUS provides the functionality of installing the bundles in the specified directory when the framework starts. However, it does not offer directory management or synchronization functions.

    The configurable items for the initial bundles directory are as follows.

    Item Description

    Install Initial Bundles

    Decides whether to install bundles in the initial bundles directory when the OSGi framework starts.

    Initial Bundles Directory Location

    Specifies the location (file path) of the initial bundles directory. If not specified, the default path used is JEUS_HOME/lib/osgi/FRAMEWORK_NAME directory.

    Default Start Level

    Specifies the default start level for the initial bundles directory.

    Fail On Error

    Decides whether to regard the failed installation of bundles as an error.

  • Bundle Installation Descriptors

    Specifies the location of bundle installation descriptor XML files. If the location is specified as a relative path, the file location is decided based on the initial bundles directory.

    The bundle installation descriptor used in the JEUS OSGi module is an XML file that contains the information about the bundles to be installed. If the user creates the bundle installation descriptor that includes information of the bundles, and specifies the XML file location in the OSGi framework configuration, the JEUS OSGi module completes the initialization process of the OSGi framework and installation of bundles in the initial bundle directory, and then reads the XML file to install bundles based on the information in the file.

    The following is an example of the bundle installation descriptor.

    Bundle Installation Descriptor Example
    <?xml version="1.0" encoding="UTF-8"?>
<bundles xmlns="http://www.tmaxsoft.com/xml/ns/jeus/osgi/bundles">
    <!-- Specifies the default start level to be applied when installing bundles specified in the XML file. -->
    <default-start-level>15</default-start-level>
    <!-- Decides whether to regard the failed bundle installation as an error. -->
    <fail-on-error>true</fail-on-error>
    <bundle>
        <!-- Specifies the start level value for bundles. This overrides the value specified in default-start-level. -->
        <start-level>5</start-level>
        <!-- Decides whether to install bundles -->
        <install>true</install>
        <!-- Decides whether to start the bundles after installation -->
        <start>true</start>
        <!-- Specifies the URL of bundles to be installed -->
        <location>http://central.maven.org/maven2/org/apache/logging/log4j/log4j-api/2.8.2/log4j-api-2.8.2.jar</location>
    </bundle>
</bundles>

3. Adding OSGi Framework Configuration

This section describes how to add OSGi framework configuration.

Using the console tool

The following is an example of adding OSGi framework configuration by using the console tool.

[MASTER]domain1.adminServer>list-osgi-frameworks
No OSGi Frameworks exists.
[MASTER]domain1.adminServer>add-osgi-framework -name framework-0 -servers server1
Successfully performed the ADD operation for OSGi Framework framework-0, but all changes were non-dynamic. They will be applied after restarting.
Check the results using "list-osgi-frameworks".
[MASTER]domain1.adminServer>list-osgi-frameworks
List of OSGi Frameworks
================================================================================
+------------------------+----------------------------+------------------------+
|     Framework Name     |      JNDI Export Name      |     Target Servers     |
+------------------------+----------------------------+------------------------+
| framework-0            |                            | server1                |
+------------------------+----------------------------+------------------------+
================================================================================
[MASTER]domain1.adminServer>

For detailed explanations of the commands used in the examples, refer to OSGi Commands in JEUS Reference Guide.

After the configuration is completed successfully, and the server restarts, the following message is displayed that OSGi framework is started successfully.

...
[2017.10.25 16:06:24][1] [server1-1] [OSGi-0003] OSGi Framework [framework-0] is started successfully.
...

4. Modifying OSGi Framework Configuration

This section describes how to modify OSGi framework configuration.

Using the console tool

The following is an example of changing OSGi framework configuration by using the console tool.

[MASTER]domain1.adminServer>list-osgi-frameworks -framework framework-0
OSGi Framework [framework-0]
================================================================================
+--------------------------------------------------------------+---------------+
|                        Attribute Name                        |     Value     |
+--------------------------------------------------------------+---------------+
| Framework Name                                               | framework-0   |
| JNDI Export Name                                             | Not Specified |
| Target Servers                                               | server1       |
| Install Initial Bundles                                      | true          |
| Initial Bundles Directory Location                           | Not Specified |
| Default Start Level                                          |            30 |
| Fail On Error                                                | true          |
+--------------------------------------------------------------+---------------+
================================================================================

Framework Configuration Properties
====================================================
+-----+--------------------------------------------+
| Key |                    Value                   |
+-----+--------------------------------------------+
(No data available)
====================================================

Bundle Installation Descriptors
================================================================================
+------------------------------------------------------------------------------+
|                                   Location                                   |
+------------------------------------------------------------------------------+
(No data available)
================================================================================
[MASTER]domain1.adminServer>modify-osgi-framework -name framework-0 -dsl 45 
Successfully performed the MODIFY operation for OSGi Framework framework-0, but some changes were non-dynamic. They will be applied after restarting.
Check the results using "list-osgi-frameworks".
[MASTER]domain1.adminServer>list-osgi-frameworks -framework framework-0
OSGi Framework [framework-0]
================================================================================
+--------------------------------------------------------------+---------------+
|                        Attribute Name                        |     Value     |
+--------------------------------------------------------------+---------------+
| Framework Name                                               | framework-0   |
| JNDI Export Name                                             | Not Specified |
| Target Servers                                               | server1       |
| Install Initial Bundles                                      | true          |
| Initial Bundles Directory Location                           | Not Specified |
| Default Start Level                                          |            45 |
| Fail On Error                                                | true          |
+--------------------------------------------------------------+---------------+
================================================================================

Framework Configuration Properties
====================================================
+-----+--------------------------------------------+
| Key |                    Value                   |
+-----+--------------------------------------------+
(No data available)
====================================================

Bundle Installation Descriptors
================================================================================
+------------------------------------------------------------------------------+
|                                   Location                                   |
+------------------------------------------------------------------------------+
(No data available)
================================================================================
[MASTER]domain1.adminServer>

  1. For detailed explanations of the commands used in the examples, refer to OSGi Commands in JEUS Reference Guide.

  2. The configuration items for OSGi on JEUS do not support dynamic configuration. To change the configuration of a running server, a server restart is necessary.

5. Deleting OSGi Framework Configuration

This section describes how to delete OSGi framework configuration.

Using the console tool

The following is an example of deleting OSGi framework configuration by using the console tool.

[MASTER]domain1.adminServer>list-osgi-frameworks
List of OSGi Frameworks
================================================================================
+------------------------+----------------------------+------------------------+
|     Framework Name     |      JNDI Export Name      |     Target Servers     |
+------------------------+----------------------------+------------------------+
| framework-0            |                            | server1                |
+------------------------+----------------------------+------------------------+
================================================================================
[MASTER]domain1.adminServer>remove-osgi-framework -name framework-0
Successfully performed the REMOVE operation for OSGi Framework framework-0.
Check the results using "list-osgi-frameworks".
[MASTER]domain1.adminServer>list-osgi-frameworks
No OSGi Frameworks exists.
[MASTER]domain1.adminServer>

  1. For detailed explanations of the commands used in the examples, refer to OSGi Commands in JEUS Reference Guide.

  2. The configuration items for OSGi on JEUS do not support dynamic configuration. To change the configuration of a running server, a server restart is necessary.

6. Access to OSGI Framework through JNDI

Once the OSGi framework is created, the JEUS OSGi module registers the system bundle context (the bundle context of the OSGi framework) in JEUS JNDI. The type of the registered object is 'org.osgi.framework.launch.Framework', and the JNDI name is the name specified in the configuration. If no name is specified, the OSGI framework name is used as the JNDI name. Applications can access the OSGi framework object through JNDI and use it if needed.

The following is an example of how to get the service object by accessing the OSGi framework object registered in JNDI with the name 'framework-0'.

Example of accessing the service object through the OSGi framework registered in JNDI
...
      InitialContext ctx = new InitialContext();
      BundleContext bundleContext = ((Framework) initialContext.lookup("framework-0")).getBundleContext();

      ServiceReference sref = bctx.getServiceReference(ServiceA.class);
...
      ServiceA service = (ServiceA)bctx.getService(sref);
...