| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <head> |
| <title>Apache Felix - Composite Bundles</title> |
| <link rel="icon" href="/res/favicon.ico"> |
| <link rel="stylesheet" href="/res/site.css" type="text/css" media="all"> |
| <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all"> |
| <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
| </head> |
| <body> |
| <div class="title"> |
| <div class="logo"> |
| <a href="https://felix.apache.org/"> |
| <img border="0" alt="Apache Felix" src="/res/logo.png"> |
| </a> |
| </div> |
| <div class="header"> |
| <a href="https://www.apache.org/"> |
| <img border="0" alt="Apache" src="/res/apache.png"> |
| </a> |
| </div> |
| </div> |
| |
| <div class="menu"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <p><a href="/news.html">News</a> <br /> |
| <a href="/license.html">License</a> <br /> |
| <a href="/downloads.cgi">Downloads</a> <br /> |
| <a href="/documentation.html">Documentation</a> <br /> |
| <a href="/documentation/community/project-info.html">Project Info</a> <br /> |
| <a href="/documentation/community/contributing.html">Contributing</a> <br /> |
| <a href="/sitemap.html">Site Map</a> <br /> |
| <a href="https://www.apache.org/">ASF</a> <br /> |
| <a href="https://www.apache.org/security/">Security</a> <br /> |
| <a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> <br /> |
| <a href="https://www.apache.org/foundation/thanks.html">Sponsors</a> </p> |
| <iframe |
| src="https://www.apache.org/ads/button.html" |
| style="border-width:0; float: left" |
| frameborder="0" |
| scrolling="no" |
| width="135" |
| height="135"> |
| </iframe> |
| </div> |
| |
| <div class="main"> |
| <div class="breadcrump" style="font-size: 80%;"> |
| <a href="/">Home</a> » <a href="/miscellaneous.html">miscellaneous</a> » <a href="/miscellaneous/sandbox.html">Sandbox</a> |
| </div> |
| |
| <h1>Composite Bundles</h1> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h1 id="1-overview">1. Overview<a class="headerlink" href="#1-overview" title="Permanent link">¶</a></h1> |
| <p>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 such issues, this proposal introduces a composite bundle concept built on top of virtual bundles.</p> |
| <p>The two main goals of this proposal are:</p> |
| <ol> |
| <li>To provide an isolation mechanism for groups of bundles, while still allowing collaboration among those groups.</li> |
| <li>To implement this mechanism as a layer above the framework.</li> |
| </ol> |
| <p>The remainder of this proposal describes the technical approach for achieving these two goals.</p> |
| <h1 id="2-use-cases">2. Use cases<a class="headerlink" href="#2-use-cases" title="Permanent link">¶</a></h1> |
| <p>Some potential use cases for composite bundles:</p> |
| <ul> |
| <li>Large application subsystems can be modeled as a composite bundle.</li> |
| <li>Different applications running in the same framework instance can be isolated from each other inside of composite bundles.</li> |
| <li>Application servers could model EARs and composite bundles to isolate inner libraries while allowing sharing from the server.</li> |
| <li>Groups of bundles needing lifecycle management as a whole can be modeled as a composite bundle.</li> |
| </ul> |
| <p>This list is not intended to be exhaustive.</p> |
| <h1 id="3-terminology">3. Terminology<a class="headerlink" href="#3-terminology" title="Permanent link">¶</a></h1> |
| <p>The following terms are used in this document:</p> |
| <ul> |
| <li>Composite bundle - a bundle whose contents is actually a set of bundles that appear to be running inside of another framework instance.</li> |
| <li>Constituent bundle - the bundles composing a composite bundle.</li> |
| <li>Parent framework - the framework in which a composite bundle is installed.</li> |
| <li>Required bundle - a bundle required by a composite bundle from the parent framework.</li> |
| <li>Provided bundle - a constituent bundle from a composite bundle made available in the parent framework. </li> |
| </ul> |
| <h1 id="4-technical-approach">4. Technical approach<a class="headerlink" href="#4-technical-approach" title="Permanent link">¶</a></h1> |
| <p>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:</p> |
| <ol> |
| <li>A simple composite model that supports only package and service sharing.</li> |
| <li>A transparent composite model that extends the simple composite model with bundle sharing.</li> |
| </ol> |
| <p>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.</p> |
| <p>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 experience is gained at which point API could potentially be introduced.</p> |
| <h2 id="41-simple-composite-model">4.1 Simple composite model<a class="headerlink" href="#41-simple-composite-model" title="Permanent link">¶</a></h2> |
| <p>The simple composite model supports installing groups of bundles as a single composite bundle with the ability to import packages/services from the parent framework into the composite bundle and to export packages/services from the composite bundle to the parent framework. The lifecycle of the constituent bundles are managed by the lifecycle of the composite bundle in the parent framework.</p> |
| <h3 id="411-simple-composite-description">4.1.1 Simple composite description<a class="headerlink" href="#411-simple-composite-description" title="Permanent link">¶</a></h3> |
| <p>A composite bundle is declared using a set of manifest-like headers, which is familiar to bundle developers and fits well with the virtual bundle proposal, where virtual bundles are installed with a given set of headers. The following headers are reused for declaring a composite bundle:</p> |
| <ul> |
| <li><code>Import-Package</code> - the packages imported by the composite bundle from the parent framework.</li> |
| <li><code>Export-Package</code> - the packages exported by the composite bundle to the parent framework.</li> |
| <li><code>Import-Service</code> - the services imported by the composite bundle (exact syntax is yet to be defined, but a list of filters is a reasonable starting point).</li> |
| <li><code>Export-Service</code> - the services exported by the composite bundle (exact syntax is yet to be defined, but a list of filters is a reasonable starting point).</li> |
| </ul> |
| <p>From the parent framework's perspective, the composite bundle is a normal bundle importing/exporting packages and services. Internally, the imported/exported packages and services are mapped onto and made available to the composite bundle's constituent bundles by the composite layer. A new header is introduced to declare the composite bundle's constituent bundles:</p> |
| <ul> |
| <li><code>Include-Bundle</code> - A comma-separate list of bundle URLs.</li> |
| </ul> |
| <p>The constituent bundles of a composite bundle are isolated from the other bundles in the parent framework. In other words, they can only see their sibling constituent bundles and bundles in the parent framework can only see the composite bundle, not its constituent bundles.</p> |
| <p>To simplify mapping a composite bundle's exported packages to its constituent bundles, this proposal introduces a new <code>from</code> directive for <code>Export-Package</code>, which is used to specify the symbolic name of the providing bundle. Consider the following composite declaration:</p> |
| <div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">ManifestVersion</span><span class="p">:</span> 2 |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">Paint</span> <span class="n">Program</span> |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">paint</span><span class="p">.</span><span class="n">composite</span> |
| <span class="n">Include</span><span class="o">-</span><span class="n">Bundle</span><span class="p">:</span> <span class="o">\</span> |
| <span class="n">file</span><span class="p">:</span><span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">rickhall</span><span class="o">/</span><span class="n">Projects</span><span class="o">/</span><span class="n">book</span><span class="o">-</span><span class="n">trunk</span><span class="o">/</span><span class="n">code</span><span class="o">/</span><span class="n">chapter04</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span><span class="n">example</span><span class="o">/</span><span class="n">bundles</span><span class="o">/</span><span class="n">shape</span><span class="o">-</span>4<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span><span class="p">,</span> <span class="o">\</span> |
| <span class="n">file</span><span class="p">:</span><span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">rickhall</span><span class="o">/</span><span class="n">Projects</span><span class="o">/</span><span class="n">book</span><span class="o">-</span><span class="n">trunk</span><span class="o">/</span><span class="n">code</span><span class="o">/</span><span class="n">chapter04</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span><span class="n">example</span><span class="o">/</span><span class="n">bundles</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span>4<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span><span class="p">,</span> <span class="o">\</span> |
| <span class="n">file</span><span class="p">:</span><span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">rickhall</span><span class="o">/</span><span class="n">Projects</span><span class="o">/</span><span class="n">book</span><span class="o">-</span><span class="n">trunk</span><span class="o">/</span><span class="n">code</span><span class="o">/</span><span class="n">chapter04</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span><span class="n">example</span><span class="o">/</span><span class="n">bundles</span><span class="o">/</span><span class="n">circle</span><span class="o">-</span>4<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span><span class="p">,</span> <span class="o">\</span> |
| <span class="n">file</span><span class="p">:</span><span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">rickhall</span><span class="o">/</span><span class="n">Projects</span><span class="o">/</span><span class="n">book</span><span class="o">-</span><span class="n">trunk</span><span class="o">/</span><span class="n">code</span><span class="o">/</span><span class="n">chapter04</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span><span class="n">example</span><span class="o">/</span><span class="n">bundles</span><span class="o">/</span><span class="n">square</span><span class="o">-</span>4<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span><span class="p">,</span> <span class="o">\</span> |
| <span class="n">file</span><span class="p">:</span><span class="o">/</span><span class="n">Users</span><span class="o">/</span><span class="n">rickhall</span><span class="o">/</span><span class="n">Projects</span><span class="o">/</span><span class="n">book</span><span class="o">-</span><span class="n">trunk</span><span class="o">/</span><span class="n">code</span><span class="o">/</span><span class="n">chapter04</span><span class="o">/</span><span class="n">paint</span><span class="o">-</span><span class="n">example</span><span class="o">/</span><span class="n">bundles</span><span class="o">/</span><span class="n">triangle</span><span class="o">-</span>4<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span> |
| <span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">shape</span><span class="p">;</span> <span class="n">from</span><span class="p">:=</span><span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">shape</span><span class="p">.</span><span class="n">bundle</span><span class="p">;</span> <span class="n">version</span><span class="p">=</span>"4<span class="p">.</span>0" |
| <span class="n">Import</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">osgi</span><span class="p">.</span><span class="n">service</span><span class="p">.</span><span class="nb">log</span><span class="p">;</span> <span class="n">version</span><span class="p">=</span>1<span class="p">.</span>0<span class="p">.</span>0 |
| <span class="n">Import</span><span class="o">-</span><span class="n">Service</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">shape</span><span class="p">.</span><span class="n">SimpleShape</span> |
| </pre></div> |
| |
| |
| <p>This composite contains five bundles and exports <code>org.foo.shape</code> from the bundle with the symbolic name <code>org.foo.shape.bundle</code>. Further, it also imports the log service package and any services implementing the <code>org.foo.shape.SimpleShape</code> interface from the package it exports.</p> |
| <p>These declarative headers define the entire capabilities of a simple composite bundle. To summarize, these capabilities are: containing bundles, importing/exporting packages, and importing/exporting services.</p> |
| <p>NOTE 1: It is not clear if <code>Import-Package</code> should essentially support an "export as" directive where the composite creator explicitly specifies how the imported package gets converted to an export internally or if this should be somehow automatically derived from the actual injected wire. If the latter, then this relates to the rich wiring section in the open issues.</p> |
| <p>NOTE 2: Any "uses" constraints for the composite bundle's exported packages must be specified in the metadata, which will be used by parent framework to ensure consistency like normal.</p> |
| <h3 id="412-simple-composite-lifecycle-management">4.1.2 Simple composite lifecycle management<a class="headerlink" href="#412-simple-composite-lifecycle-management" title="Permanent link">¶</a></h3> |
| <p>Since composite bundles are implemented as virtual bundles, access to their content and portions of their lifecycle are controlled by an external manager. This section describes various lifecycle management issues for simple composite bundles.</p> |
| <h4 id="4121-composite-manager">4.1.2.1 Composite manager<a class="headerlink" href="#4121-composite-manager" title="Permanent link">¶</a></h4> |
| <p>The composite manager results from the use of virtual bundles and is largely responsible for realizing the capabilities embodied in the composite description. This means it is the composite manager's responsibility to:</p> |
| <ul> |
| <li>Manage a composite bundle's constituent bundles.</li> |
| <li>Provide constituent bundles access to imported packages and imported services.</li> |
| <li>Provide the parent framework access to exported packages and exported services.</li> |
| <li>Manage the overall lifecycle of composite bundles.</li> |
| </ul> |
| <p>The precise approach the composite manager uses to accomplish these responsibilities is not specified, but one potential approach is for the composite manager to create a separate framework instance for each composite bundle. Another approach would be to create a static wiring of the constituent bundles and just mimic framework behavior for them.</p> |
| <h4 id="4122-installing-composites">4.1.2.2 Installing composites<a class="headerlink" href="#4122-installing-composites" title="Permanent link">¶</a></h4> |
| <p>If an "install hook" is introduced in the virtual bundle proposal, then the composite manager can use it to seamlessly install composite bundles via the <code>BundleContext.installBundle()</code> method like a normal bundle. If install hooks are not proposed, then it could provide a simple service for installing composites. A composite is installed with a complete composite description, which forms the manifest of the installed virtual bundle. As such, composite installation is effectively atomic from the perspective of the parent framework.</p> |
| <h4 id="4123-resolving-composites">4.1.2.3 Resolving composites<a class="headerlink" href="#4123-resolving-composites" title="Permanent link">¶</a></h4> |
| <p>The composite bundle's wires for its imported packages are injected into the composite's virtual module by the framework, like for all virtual bundles. The composite manager uses these wires for delegation purposes out to the parent framework for the constituent bundles. If a composite bundle is resolved, then it is possible to load classes from it.</p> |
| <p>NOTE: Resolving a composite bundle could actually be combined with some sort of verification step, where the manager verifies whether or not the composite bundle can provide what it says it can provide. It is not clear if this needs to be specified, since such verification does not happen for normal bundles. In other words, it is a reasonable approach to just trust the metadata.</p> |
| <h4 id="4124-starting-and-stopping-composites">4.1.2.4 Starting and stopping composites<a class="headerlink" href="#4124-starting-and-stopping-composites" title="Permanent link">¶</a></h4> |
| <p>Starting a composite bundle starts all internal constituent bundles. Likewise, stopping a composite bundle stops all constituent bundles. Composite bundles do not have user-defined activators, although the composite manager may make use of an activator. For active composites, the composite manager must provide constituent bundles access to services imported from the parent framework and must make exported services available in the parent framework. Conversely, when a composite bundle is no longer active, it must stop providing access to these services.</p> |
| <p>After a composite bundle is stopped, it should remain resolved and continue to provide access to its exported packages.</p> |
| <p>NOTE: Since this proposal does not propose an API to expose the constituent bundles, individual lifecycle manipulation of the constituent bundles is not expected. To keep things simple, constituent bundles are either active or not based on the state of their composite bundle. If more fine-grained control is required it would be possible. Starting and stopping individual constituent bundles would offer no real issue, although allowing them to be refreshed or uninstalled might cause the composite manager to force the outer composite bundle to refresh if the export signature is impacted.</p> |
| <h4 id="4125-updating-a-composite">4.1.2.5 Updating a composite<a class="headerlink" href="#4125-updating-a-composite" title="Permanent link">¶</a></h4> |
| <p>When a composite bundle is updated, the composite manager must continue to support the associated virtual module; i.e., it must still be possible to load classes from it. At the point in time when the bundle is refreshed and returned to the installed state, then the composite manager can dispose of the old virtual module. If the composite was updated to a normal bundle (or a different kind of virtual bundle), then the composite manager will no longer manage it. On the other hand, if was updated to another composite bundle, then the composite manager will reinstall a new virtual module for it.</p> |
| <h4 id="4126-uninstalling-a-composite">4.1.2.6 Uninstalling a composite<a class="headerlink" href="#4126-uninstalling-a-composite" title="Permanent link">¶</a></h4> |
| <p>When a bundle is uninstalled, that does not mean that it is no longer in use by the framework, since it must still be possible to load classes from it. Unfortunately, the framework provides no additional callbacks or state changes to notify when it is really done with an uninstalled bundle. As a result, if a composite bundle is uninstalled, the composite manager must immediately refresh it to perform proper clean up, since it will not get a later lifecycle callback when the uninstalled bundle is eventually refreshed.</p> |
| <p>NOTE: This could be improved with a <code>VirtualModule.dispose()</code> method, which would be invoked by the framework to indicate when it was done with the virtual module.</p> |
| <h4 id="4127-refreshing-a-composite">4.1.2.7 Refreshing a composite<a class="headerlink" href="#4127-refreshing-a-composite" title="Permanent link">¶</a></h4> |
| <p>When refreshing a composite bundle, all constituent bundles are refreshed and the composite bundle returns to the installed state. Following normal framework behavior, any bundles depending on the composite bundle will also be refreshed. Likewise, if the composite bundle depends on another bundle being refreshed in the parent framework, then it too will be refreshed.</p> |
| <h4 id="4128-relationship-to-composite-manager-lifecycle">4.1.2.8 Relationship to composite manager lifecycle<a class="headerlink" href="#4128-relationship-to-composite-manager-lifecycle" title="Permanent link">¶</a></h4> |
| <p>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.</p> |
| <h2 id="42-transparent-composite-model">4.2 Transparent composite model<a class="headerlink" href="#42-transparent-composite-model" title="Permanent link">¶</a></h2> |
| <p>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 a transparent composite model that extends the simple composite model to include additional support for provided and required bundles at the expense of added complexity.</p> |
| <h3 id="421-transparent-composite-description">4.2.1 Transparent composite description<a class="headerlink" href="#421-transparent-composite-description" title="Permanent link">¶</a></h3> |
| <p>Transparent composite bundles can require bundles using the following header:</p> |
| <ul> |
| <li><code>Require-Bundle</code> - the bundles required by the composite from the parent framework.</li> |
| </ul> |
| <p>The composite manager makes the required bundles available to the composite bundle's constituent bundles. A new header is defined to provide access to constituent bundles in the parent framework:</p> |
| <ul> |
| <li><code>Provide-Bundle</code> - a comma-delimited set of symbolic names specifying the constituent bundles provided by the composite bundle to the parent framework.</li> |
| </ul> |
| <p>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 transparent composite bundle lifecycle, more details will be present in the next section.</p> |
| <h3 id="422-transparent-composite-lifecycle-management">4.2.2 Transparent composite lifecycle management<a class="headerlink" href="#422-transparent-composite-lifecycle-management" title="Permanent link">¶</a></h3> |
| <p>To provide access to constituent bundles into the parent framework, the 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.</p> |
| <p>NOTE: Depending on how composite bundles are implemented, these issues may also apply to required bundles inside the composite bundle.</p> |
| <h4 id="4221-two-phase-resolve">4.2.2.1 Two-phase resolve<a class="headerlink" href="#4221-two-phase-resolve" title="Permanent link">¶</a></h4> |
| <p>When a composite providing access to a constituent bundle is first installed, the provided bundle cannot be made available immediately. Once the composite bundle is resolved (i.e., the composite's associated virtual module is injected with its wires), then the composite manager can install a virtual bundle proxying the provided bundle. At this point, the proxy provided bundle is available for use by other bundles in the parent framework, although it will still be in the installed state in the parent until someone actually causes it to resolve. However, resolving the proxy provided bundle technically has no real effect since it is actually resolved internal to the composite.</p> |
| <h4 id="4222-maintaining-class-space-consistency">4.2.2.2 Maintaining class space consistency<a class="headerlink" href="#4222-maintaining-class-space-consistency" title="Permanent link">¶</a></h4> |
| <p>If the packages exported by a provided bundle do not have uses constraints or if the uses constraints are confined to other packages exported by the provided bundle itself, then the proxying described in the last section is sufficient to provide access in the parent framework. On the other hand, if the provided bundle's exported packages have uses constraints on packages imported by the provided bundle, then this poses a potential issue for clients of the proxy provided bundle in the parent framework. The provided bundle's uses constraints must be modeled in the parent framework so it can maintain class space consistency.</p> |
| <p>To achieve this, when such a situation is detected, the composite manager must install an additional virtual bundle in the parent framework that acts as a uses constraint proxy bundle by exporting any packages imported by the provided bundle that are part of a uses constraint. Additionally, the proxy provided bundle must be generated such that it explicitly imports its packages from the uses constraint proxy bundle in the parent framework. This will ensure the parent framework correct observes the uses constraints and enforces them for potential clients. To clarify via an example, consider the following hypothetical (and completely irrational) composite description:</p> |
| <div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">ManifestVersion</span><span class="p">:</span> 2 |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">HTTP</span> <span class="n">Composite</span> |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">composite</span><span class="p">.</span><span class="n">http</span> |
| <span class="n">Include</span><span class="o">-</span><span class="n">Bundle</span><span class="p">:</span> <span class="o">\</span> |
| <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span><span class="p">.</span><span class="n">jar</span><span class="p">,</span> <span class="o">\</span> |
| <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">javax</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">jar</span> |
| <span class="n">Provide</span><span class="o">-</span><span class="n">Bundle</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span> |
| </pre></div> |
| |
| |
| <p>This composite contains two constituent bundles and provides access to the <code>org.foo.http</code> constituent bundle. Assume the <code>org.foo.http</code> bundle has the following metadata:</p> |
| <div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">ManifestVersion</span><span class="p">:</span> 2 |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">HTTP</span> <span class="n">Service</span> |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span> |
| <span class="n">Import</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">servlet</span><span class="p">,</span> <span class="n">javax</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">http</span> |
| <span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span><span class="p">;</span> <span class="n">uses</span><span class="p">:=</span>"<span class="n">javax</span><span class="p">.</span><span class="n">servlet</span>"<span class="p">,</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span><span class="p">.</span><span class="n">util</span> |
| </pre></div> |
| |
| |
| <p>In this case the <code>org.foo.http</code> imports two packages (<code>javax.servlet</code> and <code>javax,servlet.http</code>), presumably both come from the other constituent bundle in the composite, and exports two packages (<code>org.foo.http</code> and <code>org.foo.http.util</code>), where <code>org.foo.http</code> has a uses constraint on the imported <code>javax.servlet</code> package. To properly proxy this provided bundle, the composite manager would install a virtual bundle in the parent framework that looked like this:</p> |
| <div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">ManifestVersion</span><span class="p">:</span> 2 |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">HTTP</span> <span class="n">Service</span> |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span> |
| <span class="n">Import</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">servlet</span><span class="p">;</span> <span class="n">bundle</span><span class="o">-</span><span class="n">symbolic</span><span class="o">-</span><span class="n">name</span><span class="p">=</span>"<span class="n">USES</span><span class="p">.</span>12312" |
| <span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span><span class="p">;</span> <span class="n">uses</span><span class="p">:=</span>"<span class="n">javax</span><span class="p">.</span><span class="n">servlet</span>"<span class="p">,</span> <span class="n">org</span><span class="p">.</span><span class="n">foo</span><span class="p">.</span><span class="n">http</span><span class="p">.</span><span class="n">util</span> |
| </pre></div> |
| |
| |
| <p>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:</p> |
| <div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">ManifestVersion</span><span class="p">:</span> 2 |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">HTTP</span> <span class="n">Service</span> <span class="n">Uses</span> <span class="n">Constraints</span> |
| <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">USES</span><span class="p">.</span>12312 |
| <span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">servlet</span> |
| </pre></div> |
| |
| |
| <p>Since there is no uses constraint on the <code>javax.servlet.http</code> 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).</p> |
| <p>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 <code>Require-Bundle</code> 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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>NOTE: This approach requires richer wiring information as discussed in the open issues.</p> |
| <h4 id="4223-lifecycle-of-proxied-bundles">4.2.2.3 Lifecycle of proxied bundles<a class="headerlink" href="#4223-lifecycle-of-proxied-bundles" title="Permanent link">¶</a></h4> |
| <p>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.</p> |
| <p>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.)</p> |
| <p>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.</p> |
| <h1 id="5-open-issues">5. Open issues<a class="headerlink" href="#5-open-issues" title="Permanent link">¶</a></h1> |
| <h2 id="51-rich-wiring-information">5.1 Rich wiring information<a class="headerlink" href="#51-rich-wiring-information" title="Permanent link">¶</a></h2> |
| <p>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.</p> |
| <h1 id="6-considered-alternatives">6. Considered alternatives<a class="headerlink" href="#6-considered-alternatives" title="Permanent link">¶</a></h1> |
| <h2 id="scoping-approach">Scoping approach<a class="headerlink" href="#scoping-approach" title="Permanent link">¶</a></h2> |
| <p>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 <code>INSTALLED</code> 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.</p> |
| <p>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.</p> |
| <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> |
| Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000 |
| </div> |
| <div class="trademarkFooter"> |
| Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project |
| logo are trademarks of The Apache Software Foundation. All other marks mentioned |
| may be trademarks or registered trademarks of their respective owners. |
| </div> |
| </div> |
| </body> |
| </html> |
