Coalevo Architecture - Bundle Anatomy

This document presents an overview of the general anatomy of Coalevo bundles and some details on elements that form part of the foundation and system service building blocks that were presented in the architecture overview.

Bundles are the components of any OSGi framework based platform. They provide a manageable development and deployment unit that can be installed into any standard conformant OSGi framework container.

A bundle is essentially a JAR file that contains:

1. code, in form of Java classes; and
2. data, in form of metadata, configuration and resource files.

A Coalevo bundle is exactly the same thing, except that there is an additional logical organization for the code and data contained in a bundle.

The code part of a Coalevo bundle is primarily organized into

1. a public; and
2. a private part.

The public part is comprised of a model and a service package, which are both exported and allow the service capabilities to be used without needing to know all the details.

The private part is comprised of all implementation related packages (most common the impl and sometimes a util package). These are not exported and their inner working does not need to be known to a service consumer at all.

The data part of any bundle should always contain the bundle descriptor, a properties file that explicitly describes the bundle and its imports and exports. This descriptor is nothing else but the manifest file of the JAR (i.e. META-INF/MANIFEST.MF):

        Manifest-Version: 1.0
        Ant-Version: Apache Ant 1.7.0
        Created-By: 1.5.0_13-119 (Apple Inc.)
        Built-By: wimpi
        Build-Number: 6
        Bundle-ManifestVersion: 2
        Bundle-RequiredExecutionEnvironment: J2SE-1.5
        Bundle-Name: Coalevo Text Bundle
        Bundle-SymbolicName: coalevo-text
        Bundle-Version: 0.0.1
        Bundle-Description: Text Utility and Service Bundle for the Coalevo Platform
        Bundle-Activator: net.coalevo.text.impl.Activator
        Bundle-Category: service
        Bundle-Classpath: .
        Bundle-ContactAddress: bundles at coalevo.net
        Bundle-Vendor: VFI (http://www.vfi.or.at)
        Bundle-Copyright: 2006-2008 VFI (http://www.vfi.or.at)
        Bundle-DocUrl: http://www.coalevo.net/architecture/bundles/text
        Import-Package: org.osgi.framework, org.apache.commons.logging,org.apache.commons.collections,org.apache.commons.collections.list,org.apache.commons.pool,org.apache.commons.pool.impl
        Export-Package:  net.coalevo.text.service,net.coalevo.text.model,net.coalevo.text.util
        

Coalevo subprojects add this information at build time, when the bundle is packaged.

The above described anatomy is visualized in an UML package diagram in the following figure:

In addition to the standard descriptor, Coalevo bundles may contain other data files for:

• localization;
• bundle configuration; and
• bundle security.

These data files are discussed in the following subsections. Note that the list is not exclusive, but rather concentrates on the elements that are most common for Coalevo bundles.

Localization data

Internationalized software is an important aspect in todays globalized environment, especifically if the software is all about communication.

The Coalevo platform takes this aspect into account, and provides the ability for bundles to carry localized message resources.

Currently, there are commonly two types of localizable data files:

1. message resources that are related the MessageResourceService; and
2. message resources that are related to configuration handling in bundles, respectively allow to present localized configuration descriptions.

The first are comprised of well formed XML files that carry message templates (based on StringTemplate, which gives much more flexibility than standard ResourceBundles and java.text) that are used through the MessageResourceService. The mechanism for loading the resources operates similar to the one for the standard ResourceBundle (i.e. localized files should carry the locale as suffix).

The latter are comprised of standard Properties based ResourceBundles and are actually used by and through the MetaTypeService.

In existing subprojects, this files are kept in a resource package of the subproject package and are added to the bundle JAR file in the location OSGI-INF/l10n/.

Bundle configuration data

Configuration data is another important aspect, especially when it comes to software deployment.

Coalevo bundles make use of the MetaTypeService, providing a descriptor file that specifies the configuration data for a service or bundle.

The descriptor file is essentially an XML file that provides a description of the configuration data, its types and default/initial values.

In existing subprojects, this files are kept in a resource package of the subproject package and are added to the bundle JAR file in the location OSGI-INF/metatype/.

Note

The MetaType mechanism also permits the Coalevo Desktop Manager to auto-generate a localized configuration dialog (see the following figure) with validated/validateable inputs (because types are known).

Bundle security data

When installing bundles that provide services, there needs to be a mechanism that initializes the service policy for interaction with the service.

Coalevo bundles using the platform security should always contain an initial policy file in the bundle JAR. Essentially these files are well formed XML that correlates service actions with specific authorization rules written in SARL.

In existing subprojects, this files are kept in a resource package of the subproject package and are added to the bundle JAR file in the location COALEVO-INF/security/.