...

The OSGi framework supports deploying bundles into a flat and basically globally bundle space. The idea behind this approach can be summarized as, "the deployed set of bundles is your application configuration." This approach has performed well over the years; however, as OSGi technology is used in more and more complicated scenarios, this approach is not always sufficient. For example, when trying to run multiple applications in a single framework instance or when applications become so large that sets of bundles start mapping onto logical subsystems. In these types of situations, it is possible for the configurations of different applications or subsystems to interfere with each other. To address some of these such issues, this proposal introduces a composite bundle concept built on top of virtual bundles.

The two main goal goals of this proposal is to are:

1. To provide an isolation mechanism for groups of bundles, while still allowing collaboration among those groups

...

1. .
2. To implement this mechanism as a layer above the framework.

The remainder of this proposal describes the technical approach for achieving these two goals.

2. Use cases

Some potential use cases for composite bundles:

• Large application subsystems can be modeled as a composite bundle.
• Different applications running in the same framework instance can be isolated from each other inside of composite bundles.
• Web Application servers could model EARs and composite bundles to isolate inner libraries while allowing sharing from the server.
• Groups of bundles needing lifecycle management as a whole can be modeled as a composite bundle.

...

The overall technical approach is to use the virtual bundle concept (proposed separately) to manage composite bundles as a layer above the framework. This proposal forgoes an API-based approach to support a simple, declarative approach. The technical approach is divided into two halves for supporting a more simplistic composite model and extending this model to support additional scenarios at the expense of making it more complicated.:

1. A simple composite model that supports only package and service sharing.
2. A transparent composite model that extends the simple composite model with bundle sharing.

NOTE 1: The purpose is not to actually treat the two models as separate entities, but to more clearly illustrate the extra cost in complexity by supporting transparency.

NOTE 2: Although this document is API-less, the goal is not to completely rule out any API, but to keep things simple until some real-world NOTE: The goal is not to completely rule out any API, but to keep things simple until some real-world experience is gained at which point API could potentially be introduced.

...

Bundle-ManifestVersion: 2
Bundle-Name: Paint Program
Bundle-SymbolicName: org.foo.paint.composite
Include-Bundle: \
 file:/Users/rickhall/Projects/book-trunk/code/chapter04/paint-example/bundles/shape-4.0.jar, \
 file:/Users/rickhall/Projects/book-trunk/code/chapter04/paint-example/bundles/paint-4.0.jar, \
 file:/Users/rickhall/Projects/book-trunk/code/chapter04/paint-example/bundles/circle-4.0.jar, \
 file:/Users/rickhall/Projects/book-trunk/code/chapter04/paint-example/bundles/square-4.0.jar, \
 file:/Users/rickhall/Projects/book-trunk/code/chapter04/paint-example/bundles/triangle-4.0.jar
Export-Package: org.foo.shape; from:=org.foo.shape.bundle; version="4.0"
Import-Package: org.osgi.service.log; version=1.0.0
Import-Service: org.foo.shape.SimpleShape

This composite contains five bundles and exports org.foo.shape from the bundle with the symbolic name org.foo.shape.bundle. Further, it also imports the log service package and any services implementing the org.foo.shape.SimpleShape interface from the package it exports.

...

Since the composite manager manages all aspects of the composite's content, its active lifetime scopes its managed composites. In other words, if the composite manager is stopped, then it explicitly causes all of its managed composites to refresh and return to the installed state.

4.2

...

Transparent composite model

The simple composite model fits fairly well within the constraints of the OSGi framework since it aligns well with the concepts embodied in the original OSGi specification (i.e., packages and services). However, some use cases may require support beyond these original concepts. For such cases, this proposal defines the extended a transparent composite model as an extension of that extends the simple composite model that includes to include additional support for provided and required bundles at the expense of added complexity.

4.2.1

...

Transparent composite description

Extended Transparent composite bundles can require bundles using the following header:

...

The provided bundles will be manifested in the parent framework as virtual bundles themselves. This means that in addition to the composite bundle in the parent framework, there will ultimately be additional virtual bundles installed by the composite manager for each provided bundle; since this is related to the extended transparent composite bundle lifecycle, more details will be present in the next section.

4.2.2

...

Transparent composite lifecycle management

To provide access to constituent bundles into the parent framework, the extended composite manager must proxy provided constituent bundles as separate virtual bundles in the parent framework. This complicates lifecycle management since it creates separate points of control for the composite bundle and it also complicates maintaining class space consistency for clients of the provided bundle. This section discusses these issues in more detail.

...

Bundle-ManifestVersion: 2
Bundle-Name: PaintHTTP ProgramComposite
Bundle-SymbolicName: org.foo.paintcomposite.compositehttp
Include-Bundle: \
 http://www.foo.org/httpserviceorg.foo.http.jar, \
 http://www.foo.org/javax.servlet.jar
Provide-Bundle: org.foo.http

This composite contains two constituent bundles and provides access to the org.foo.http constituent bundle. Assume the org.foo.http bundle has the following metadata:

Bundle-ManifestVersion: 2
Bundle-Name: HTTP Service
Bundle-SymbolicName: org.foo.http
Import-Package: javax.servlet, javax.servlet.http
Export-Package: org.foo.http; uses:="javax.servlet"

, org.foo.http.util

In this case the org.foo.http

...

imports two packages (javax.servlet and javax,servlet.http), presumably both come from the other constituent bundle in the composite, and exports two packages (org.foo.http and org.foo.http.util), where org.foo.http has a uses constraint on the imported javax.servlet package. To properly proxy this provided bundle, the composite manager would install a virtual bundle in the parent framework that looked like this:

Bundle-

Bundle-ManifestVersion: 2
Bundle-Name: HTTP Service Uses Constraints
Bundle-SymbolicName: org.foo.http
Import-Package: javax.servlet; bundle-symbolic-name="USES.12312"
Export-Package: org.foo.http; uses:="javax.servlet

Discuss: 1) two-phase nature 2) uses constraints and 3) lifecycle ops on provided bundles

NOTE: For a provided bundle into the parent framework, it is not clear how we should tie its lifecycle to the corresponding constituent bundle and/or whether it should be controllable in the parent framework. For simplicity, it is probably better to effectively make it a no-op.

When refreshing a composite, all constituent bundles are refreshed and the composite bundle returns to the installed state. Any provided bundles in the parent framework will also be refreshed and returned to the installed state and will not be resolvable until the composite is resolved.

NOTE 1: Another approach for provided bundles is to uninstall and refresh them.

NOTE 2: Refreshing a provided bundle should likely be a no-op internal to the composite bundle, although it will cause a refresh of dependent bundles in the parent framework.

4.1.2.8 Lifecycle flow

Lifecycle control flows down, not up

5. Open issues

5.1 Rich wiring information

Currently, the wiring information provided by the virtual bundle proposal has been kept purposely simplistic. To fully implement aspects of composites, like requiring/providing bundles, it is necessary to get richer information from the wires, such as the type of capability. Further, the wiring information needs to be at the module-level (i.e., bundle revision level), not at the bundle level.

6. Considered alternatives

", org.foo.http.util

This proxy provided bundle enables access to the exported packages of the original provided bundle and correctly models its uses constraints on a second uses constraint virtual bundle. The composite manager generates the proxy provided bundle metadata so that it can only resolve to the generated uses constraint virtual bundle, which would look something like this:

Bundle-ManifestVersion: 2
Bundle-Name: HTTP Service Uses Constraints
Bundle-SymbolicName: USES.12312
Export-Package: javax.servlet

Since there is no uses constraint on the javax.servlet.http package, then it need not be provided by the uses constraint bundle. On the other hand, if there was then it would need to be exported as well. Further, if these exported packages had uses constraints on other imported packages, then these would need to be modeled as well. However, these could be modeled by simply having the uses constraint bundle export them in addition to the original exports (effectively reexporting the imported packages).

NOTE: The approach to proxy the provided bundle as two bundles (the proxy bundle and the uses constraint bundle) is necessary to maintain the semantics of Require-Bundle which only gives access to the target bundle's exported packages. A different, but not completely consistent approach is to just proxy the provided bundle and turn all of its imports into exports so that all uses constraints are satisfied by the proxy itself. The main downside of this approach is that client bundles in the parent framework would end up with greater visibility of packages than if they required the bundle directly.

If a composite provides multiple bundles, then shared and potentially conflicting packages among the provided bundles would need to be correctly modeled. For each provided bundle, a package space would need to be calculated for any imported package participating in a uses constraint. Any common packages with the same provider among the provided bundles would need to be modeled on a common uses constraint bundle in the parent framework, where the same package coming from different providers would need to be modeled with a separate uses constraint bundles. Non-overlapping packages could be lumped into a single uses constraint bundle. This algorithm would be non-trivial, but since it is just walking existing wires, it should not suffer from similar performance issues like the resolver algorithm.

One special case to note, if the provided bundle has a uses constraint on an imported package that was actually imported from the parent framework via the composite description, then it is not necessary to model this import in the parent framework since it already exists. For this case, the generated proxy provided bundle must simply explicitly import the package from the original bundle in the parent framework.

NOTE: This approach requires richer wiring information as discussed in the open issues.

4.2.2.3 Lifecycle of proxied bundles

As discussed, the support for providing bundles results in the composite manager installing proxy bundles for the provided bundle and its uses constraints in the parent framework in addition to the original composite bundle. This raises questions about the lifecycle of proxied bundles.

The lifetime of the proxied bundles is dependent on the resolved lifetime of the associated composite bundle. If the composite is refreshed, then the provided bundles should be uninstalled and refreshed. (Technically, it would be possible to simply refresh them and leave them unresolvable.)

Performing individual lifecycle operations on the proxied bundles should function like normal in the parent framework, but should have no impact on the internal constituent bundles of the composite. For example, you can start, stop, and even uninstall provided bundles, but this just impacts the state of the bundles in the parent framework, which may render them unresolvable.

5. Open issues

5.1 Rich wiring information

Currently, the wiring information provided by the virtual bundle proposal has been kept purposely simplistic. To fully implement aspects of composites, like requiring/providing bundles, it is necessary to get richer information from the wires, such as the type of capability. Further, the wiring information needs to be at the module-level (i.e., bundle revision level), not at the bundle level. The refactoring of the Package Admin API addresses some of these issues, but not all of them.

6. Considered alternatives

Scoping approach

Another potential approach for providing similar capabilities is to try to use virtual bundles to implement a scoping approach. Scoping can be modeled reasonably well as manifest rewriting (i.e., mandatory attributes and renaming). If it were possible to install bundles and "lock" them in the INSTALLED state, then these bundles could be used like templates for creating scopes via manifest rewriting in a virtual bundle. The same template bundle could be copied into different scopes using different virtual bundles in the different scopes or could be shared among scopes by appropriately rewriting the metadata. This approach could also scope the service registry, since it would be possible to inject proxied bundle contexts into the scoped bundles (via their virtual bundle wrapper) that only show services in the appropriate scope.

The biggest issue here is achieving complete fidelity with the OSGi specification for handling of bundles. The virtual bundle mechanism would need to include support for dynamic imports, fragments, and lazy activation. All of these are potentially feasible, but would need to be fleshed out.TBD