Starting the framework

Overview

You can start the OSGi framework:

• From a shell script file for a specific VM.
• From the command line by calling its main Java class.
• By using the Framework Factory.

The Runtime supports JVMs that are most suitable for using on resource-constrained systems and could be configured in a way to provide the best cooperation between the OSGi framework and the Java environment.

By Using a Shell Script

To start the OSGi framework by executing a shell script file:

• Go to the <gateway_home>/osgi-runtime/osgi installation directory.
• Explore the bin/vms/<vm_name> folder where <vm_name> is the directory name that matches the name of the JVM the device uses. For example, if JDK is the current JVM on your development computer, go to bin/vms/jdk.
• Start the appropriate server script file in that directory.

  For launching the framework with specific features active, open a shell in the directory and call server by using a command line:

  server <options>

where <options> stands for the server options activating the relevant features separated with spaces.

On Windows Vista and Windows 7, you need admin rights to install all components of the OSGi Runtime. In case, you do not have them, some of the server scripts might not be installed.

By using the main class of the framework

To start the framework from the command line by calling its main Java class:

• Set the system class path to the lib/framework/serverXxx.jar where the framework components are packed.
• Run the com.prosyst.mbs.impl.framework.Start class according to the semantics of the used JVM.

Usage:

<command> [options] com.prosyst.mbs.impl.framework.Start

where:

• <command> stands for the executable that starts the desired JVM. For example, for JDK this command is java.
• options stands for command options and system properties.

You might also add arguments to the Start main class which interested applications can read by using the Framework Access service - see the service description in the System Bundle.

When launching the framework by using its main class, to avoid too many characters in the command line, you may specify the location of a property file holding system properties for tuning the startup process of the framework. This is done through the mbs.prs.name system property, which specifies the name(s) of the properties file(s).

For example if using JDK:

Windows:

java -Dmbs.prs.name=c:/init/gateway/myproperties.prs com.prosyst.mbs.impl.framework.Start

Linux:

java -Dmbs.prs.name=/home/user/init/gateway/myproperties.prs com.prosyst.mbs.impl.framework.Start

In this file you may designate:

• The Startup Bundles List file, listing the management bundles to be installed at startup.
• The main directory where most of the bundles to install are located.
• The Storage Properties of the framework (refer to the Storage Properties from the Setup Guide).
• etc.

Initially, the framework loads its system properties from the default.prs file located in the current startup directory and from common.prs located in the bin/vms directory.

For more information about the system properties discussed above, refer to the System Properties section in the Setup Guide.

By using the framework factory

Another option to launch the OSGi framework is programmatically by using the Framework Factory specified in the OSGi Framework Launcher API – org.osgi.framework.launch. Launchers can launch the framework from the JVM-specific lib/framework/serverXxx.jar files and retrieve the Framework Factory implementation from the META-INF/services/org.osgi.framework.launch.FrameworkFactory text file inside the JAR file. As input argument to the newFramework method of the Framework Factory pass needed system properties as specified in the OSGi Service Platform Core Specification and in System Properties (refer to the System Properties section in the Setup Guide).

Framework startup

Before the framework can be used, it must be initialized. Initialization is caused by one of the init methods or implicitly by the start method. The start method moves the framework into the ACTIVE state. If the framework was not initialized, it must be initialized first. An initialized framework is operational, but none of its bundles are active. A framework object can be initialized multiple times. After initialization:

• Event handling is enabled.
• The security manager is configured.
• Start level is set to 0.
• The framework object has a valid Bundle Context.
• Any installed bundle is in the INSTALLED or RESOLVED state.
• Framework services are available.
• The framework state is STARTING.
• Has a valid UUID.
• The system bundle can adapt to any of its defined types.
• All resolved extension bundle activators start methods have been called.

After the System bundle enters the ACTIVE state, a Framework STARTED event is broadcast.

When the framework is started, it performs the operations:

• Loads the Framework Measurement (refer to the Framework Measurement section in the Framework architecture document) and Framework Loader (refer to the Framework Loader section in the Framework architecture document) modules, if specified.
• Loads the system properties (refer to the Runtime System Properties section in the Changing settings document) from the command line and/or from property files.
• Validates the serial number of the framework.
• Redirects the output from the local console to a remote host, if specified.
• If there is no ready storage, installs and starts the essential runtime bundles listed in the startup bundles list file. If there is ready storage of installed bundles (the bin/vms/<vm_name>/storage directory is populated with data), the framework loads the bundles and their data from there.

To notify an external process that the framework has successfully started, use the mbs.start.notify.file system property (refer to "Startup and Shutdown Properties" section in the Setup guide).

Listing and getting help about "server" options

Use the "help" option of the server script if you are not aware of the common and JVM-specific options available when using the server script to start the OSGi Runtime. Open a console in the bin/vms/<vm_name> directory and type

server help

Starting the framework with security

When started with security turned on, the Security Manager of the framework uses the Security module for security-related operations. The default implementation of the Security module relies on the Java 2 security model and utilities. Currently it is supported on most JVMs. However, it is possible to implement a custom Security implementation, if such is required for specific purposes.

Using the security option

Open a command prompt in the JVM-specific startup directory of the framework and type:

server security

If you have problems with starting the framework with security clean its storage and try again.

Policy file

The framework will not start if you do not point to a policy file with the permissions that will be assigned to the framework implementation classes. The file is passed through the java.security.policy system property. It is recommended that you use the policy.all file from the bin/vms directory of the OSGi Runtime. The java.security.policy should be specified in the starting script of the framework complying with the system properties' syntax of the used JVM.

These permissions will not be applied to bundle classes. To manage bundle permissions, use the OSGi Permission Admin and Conditional Permission Admin services.

Starting the framework with clean storage

You can start the framework with empty storage so that the initial set of bundles installed at startup is determined by the Boot module (refer to the Boot section in the Framework architecture document), i.e. from a file containing the startup bundles list. Use the clean option to the JVM-specific server script.

server clean

JVMs for which the starting scripts support the clean option: All.

Starting the framework with disabled certificate management

On framework startup the Certificate manager module (refer to the Certificate manager section in the Framework architecture document) is enabled by default. Certificate management includes loading of certificates from a specific storage (keystore or directory) and providing utilities for comparing the DNs of two certificates.

To disable certificate management use the nocert option to the JVM-specific server script.

server nocert

JVMs for which the starting scripts support the nocert option: All.

Having CertificateManager service disabled with 'server nocert' is the recommended way for every customer using a secure connection to register their own implementations of KeyManager and TrustManager with a secure context bundle. Another way for custom implementations of these services is to register them with service.ranking higher than 0, which is the default rank.

Starting the Framework with disabled lazy Initialization

The server starting script from the bin/vms/<vm_name> directory starts the framework with lazy initialization enabled (refer to the Lazy Initialization guide). To turn this feature off, use the nolazy option of the script.

Open a command prompt in the JVM-specific startup directory of the framework and type:

server nolazy

JVMs for which the starting scripts support the nolazy option: All.

Starting the framework with errors logged

You can conveniently launch the framework with active error log directly by using the fwerr option to the JVM-specific server script.

server fwerr

JVMs for which the starting scripts support the fwerr option: All.

Starting the framework with enabled framework extensions

You can start the framework with active support for framework extension bundles by using the fwext option to the JVM-specific server script.

server fwext

JVMs for which the starting scripts support the fwext option: All.

Starting the framework with framework loader

You can conveniently launch the framework with active Framework Loader (refer to the Framework Loader section in the Framework architecture document) directly by using the fwloader option to the JVM-specific server script.

server fwloader

JVMs for which the starting scripts support the fwloader option: All.

Starting the framework with JIT

You can launch the framework on the JVM with enabled just-in-time (JIT) compilation for faster execution. Use the jit option to the JVM-specific server script.

server jit

JVMs for which the starting scripts support the jit option: All JVMs which provide support for JIT.

Starting the framework for JDWP debugging

You can start the framework for remote debugging over the Java Debug Wire Protocol (JDWP). Use one of the following options to the JVM-specific server script:

• debug – The JVM running the OSGi framework will start in debug mode.
• dbg_suspend – The JVM will be immediately instructed to suspend its execution until a debug client UI connects.
• dbg_nosuspend – The JVM will not be suspended. Use this option if the debug UI will be started before the framework.
• dbg_port <port_number> – The port on which the framework should listen for debug information requests. Use it if the debugging port should be different from 8000.

  server debug dbg_suspend|dbg_nosuspend dbg_port 8088

JVMs for which the starting scripts support the debug/dbg_suspend option: JDK, Skelmir CEE-J® VM and Aonix Perc® Ultra.

Starting the framework with logger disabled

By default, the framework is started with log information from the Framework Log and from the OSGi Log Service saved in files within the bin/vms/<vm_name> directory. To disable this features, use the nofilelog option of the server script:

server nofilelog

JVMs for which the starting scripts support the nofilelog option: All.

Starting the framework from mBSA

You can launch the OSGi framework by using the emBedded System Agent (mBSA) thus providing support at OS-native level for managing framework's state. Refer to the mBSA documentation.

Starting the framework with measurements

You can start the framework with lazy initialization turned on by using the "measurements" option to the starting script (server from bin/vms/<vm_name>). Open a command prompt in the JVM-specific startup directory of the framework and type:

server measurements

JVMs for which the starting scripts support the measurements option: All.

Starting the framework in the server script process

With the exec option you run the java process in the same process as the server script instead of spawning a new child process. By default the exec option is not activated.

server exec

Running the java process in the server script process is required, e.g. when running the framework in a container.

JVMs for which the starting scripts support the exec option: All.

Starting the framework with uncaught exception handling

If you have an implementation of the Uncaught exception manager, to make the framework contact it in cases of uncaught exceptions, you have to explicitly activate this feature upon startup by using the uem option of the server script:

server uem

JVMs for which the starting scripts support the uem option: All.

Starting the framework by using the application class loader

To start the framework by loading its classes with the application class loader instead of with the boot class loader, use the appcp option of the JVM-specific server script:

server appcp

JVMs for which the starting scripts support the appcp option: JDK, Skelmir CEE-J® VM.