Lazy Initialization

This document discusses the lazy initialization feature of the framework and provides basic guidelines about the feature's usage and setup.

Contents:

• Overview
  • Lazy Bundles
  • States of a Lazy Bundle
• Declaring a Service as Lazy
• Matching Requirements for a Lazy Service
  • Interface Classes Matching
  • Properties Matching
  • Registration Requirement
• Defining a Lazy Condition in a Bundle
• Defining a Lazy Manifest Condition in a Bundle
• Lazy Bundles Management
  • Startup
  • Processing Lazy Services
  • Handling Bundles with Lazy Conditions
  • Delivering Events
  • Managing Lazy Bundles in a Programming Way
• Lazy Services and Bundles in the Text Console
• Setup

Overview

The mBS framework is capable of installing certain bundles without loading their classes until they are really needed. This class loading "on demand" speeds up greatly the initial startup time of the framework.

Lazy Bundles

Three types of bundles can be subject of lazy initialization:

• Providing service classes
• Consuming services
• Having dependencies on other bundles, which have specific manifest headers

We'll consider all of these bundle types as lazy bundles.

States of a Lazy Bundle

This section discusses the states and transitions that a bundle passes during its lifecycle in regard to lazy initialization.

Declaring a Service as Lazy

When a bundle registers a service as lazy, the framework registers the service without actually starting the bundle until there is another bundle requesting the provided service object. Of course, a service provider bundle can register non-lazy services as well - they are handled in the conventional OSGi-defined way.

Declaring specific services of a bundle as "lazy" can be done by using a special header in the bundle manifest, called Provided-Services.

Provided-Services ::= lazy_clause (',' lazy_clause)*
lazy_clause ::= class (';' class)* (';' property)*
class ::= 'class=' <fully_qualified_class_name>
property ::= key '=' value
key ::= string
value ::= string

For example:

Provided-Services: class=com.prosyst.util.pcommands.PluggableCommands;group=kitman;description=Holds the Kit Manager commands

Note: As a single URL Stream Handler service may support more than one URL scheme as well as a Content Handler service may handle more than one content type, in a lazy service declaration you can use the "$" separator to specify several values to the "url.handler.protocol" property for a URL Stream Handler and to the "url.content.mimetype" property for a Content Handler.

Matching Requirements for a Lazy Service

Interface Classes Matching

All interfaces that are declared in the Provided-Services manifest header for a lazy service must match exactly to all interface classes specified in the real service registration.

Properties Matching

The properties in the lazy service declaration within the Provided-Services header must match the ones provided in the real service registration (keys are not case sensitive). In addition, the real service is allowed to have more properties than the lazy one.

Registration Requirement

The service provider bundle must register the lazy service in the terms of the OSGi Framework Specification (by using the registerService method of the corresponding BundleContext) during startup (in the body of the activator's start method).

Defining a Lazy Service Condition in a Bundle

Service consumer bundles can declare a specific condition on the availability of a service with specific properties. If the condition is not satisfied, that is, the service is not present in the service registry, the framework starts lazily the bundle. When the service(s) matching the condition becomes registered, the bundle enters the conventionalACTIVE state.

Similarly to declaring a lazy service, a lazy start condition in a service consumer bundle can be defined again in a manifest header - Lazy-Filter, which should contain an LDAP filter for registered services compliant with the OSGi Service Platform Core Specification.

For example:

Lazy-Filter:
   (&(|(objectclass=org.osgi.service.Device)(DEVICE_CATEGORY=*))
      (objectclass=org.osgi.service.Driver))

Defining a Lazy Manifest Condition in a Bundle

A bundle may use specific type of bundles, indicated through the presence of a specific manifest header with specific content. If there is no bundle containing the declared manifest information, the manifest dependent bundles is started lazily.

A lazy start condition in a manifest dependent bundle can be defined again in a manifest header - Lazy-ManifestFilter, which should contain an OSGi-compliant LDAP filter for specific content of manifest headers.

For example:

Lazy-ManifestFilter:
  (|(Bundle-SymbolicName=com.prosyst.mbs.useradminex)
     (Bundle-Name=*com.prosyst.mbs.services.useradmin))

Tip: To achieve better performence, you may include in the mbs.bundles.cacheHeaders system property the manifest headers used as filter attributes. In such case, the framework will cache the header and will execute the check operation faster.

Lazy Bundles Management

Startup

If a bundle is lazy, that is, it declares a lazy service or a lazy service or manifest condition, its start includes only registering the lazy service or condition in the service manager, respectively, and setting its state from RESOLVED to ACTIVE.

Processing Lazy Services

The framework performs the following operations for a lazily-registered service:

When the real service registration takes place at bundle startup, the framework checks if the service is registered by a lazy bundle and all registration properties match.

A real service registration is considered as equal to a lazy service declaration only if the object classes are equal and the properties in the lazy declaration match the real service's properties.

On success, the framework returns a lazy service registration object to the service provider bundle. Otherwise, the registration object for the lazy service is null.

If the start method of the bundle activator succeeds, then all bundle's lazy services are initialized.

Tip: If a lazy service is not initialized, check the Provided-Services manifest header for errors.

Handling Bundles with Lazy Conditions

If the Lazy-Filter or Lazy-ManifestFilter header is present in a bundle’s manifest, then an LDAP Filter is created by using the "lazy" manifest field. This filter is registered in the Service Manager or in the Bundle Manager, and when all conditions described in it are fulfilled, the bundle is started and its classes loaded.

Delivering Events

The framework provides registered service listeners with the following event notifications related to lazy initialization of service:

• When a lazy service is registered, the framework generates a REGISTERED ServiceEvent.
• When the lazy service is replaced by the real one, the framework fires a MODIFIED ServiceEvent.

Managing Lazy Bundles in a Programming Way

You can use the Framework Access service (com.prosyst.mbs.framework.access.FrameworkAccess) to check if a bundle is lazy and if a service is lazily registered, and to start a lazy bundle by preserving its lazy features. See the "System Bundle" document for more details.

Lazy Services and Bundles in the Text Console

The framework's text console indicates lazy services and bundles in the following way:

• As a result of the list command - By displaying the “[lazy]” keyword in front of the state of lazy bundles.
• As a result of the services command - By displaying the “Fake Service Registration” notice after the object class of the corresponding lazy service. Otherwise, “Real Service Registration” is shown.

Setup

By default, the lazy initialization of the mBS framework is turned off. To enable it, before framework startup set the mbs.bundles.lazy system property to true.

On most JVMs the mBS framework can be easily started in lazy initialization mode by passing the lazy option to the corresponding server or serverconn script file. See "Starting the Framework in Lazy Mode" for further information.

Framework Architecture