You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Apache Felix OSGi Bundle Repository (OBR)

Overview

The goal of the Apache Felix OSGi Bundle Repository (OBR) is two-fold:

  1. To simplify deploying and using available bundles with Felix.
  2. To encourage independent bundle development so that communities of interest can grow.

OBR achieves the first goal by providing a service that can automatically install a bundle, with its deployment dependencies, from a bundle repository. This makes it easier for people to experiment with existing bundles. The second goal is achieved by raising the visibility of the available bundles and providing access to both the executable bundle and its source code. Hopefully, by making OBR and the bundles themselves more visible, community members will be encouraged to provide or improve service implementations.

Note: OBR provides access to the Felix' default bundle repository, but you can also use it to deploy your own bundles by creating a bundle repository metadata file for your local bundles; see the obr list-url, obr add-url, and obr remove-url commands for more details.

Approach

For the most part, OBR is quite simple. There does not need to be a "repository server" for OBR, since nearly all functionality resides on the client side. OBR provides its functionality by reading an XML-based meta-data file that describes the bundles available to it. The meta-data file essentially contains an XML encoding of the bundles' manifest information; the next section describes the meta-data in more detail. From the meta-data, OBR is able to construct dependency information for deploying (i.e., installing and updating) bundles.

Two important pieces of meta-data are Bundle-SymbolicName and Bundle-Version; these are standard OSGi bundle manifest attributes that OBR uses to uniquely identify a bundle. For example, if you want to use OBR to update a locally installed bundle, OBR gets its symbolic name and version and searches the repository metadata for a matching symbolic name. If the matching symbolic name is found, then OBR checks if there is a newer version than the local copy using the bundle version number. Thus, the symbolic name plus bundle version forms a unique key to match locally installed bundles to remotely available bundles.

The following pseudo-Java code illustrates OBR's generic deployment algorithm:

public void deploy(String symbolicName, Version version)
{
    // Verify that the remote bundle is available.

    if (isRemoteBundleAvailable(symbolicName, version))
    {
        // Deploy the bundle's dependencies.
        deployDependencies(symbolicName, version);

        // If the bundle is already installed locally,
        // then update it to the desird version.

        if (isLocallyInstalled(symbolicName))
        {
            update(symbolicName, version);
        }

        // Else if the bundle is not installed locally, then
        // install the desired version.

        else
        {
            install(symbolicName, version);
        }
    }
}

public void deployDependencies(String symbolicName, Version version)
{
    Dependency[] deps = getDependencies(symbolicName, version);
    for (int i = 0; i < deps.length; i++)
    {
        if (!isLocallyResolvable(deps[i]))
        {
            Resource resource = findResolvingResource(deps[i]);
            deploy(resource.getSymbolicName(), resource.get);
        }
    }
}

public String findResolvingResource(Dependency deps)
{
    // Get all candidate resources in the remote repository that
    // provide a capability that resolves the dependency. From these
    // candidates, select a single resource such that if one of the
    // candidates is an update to a locally installed bundle choose it,
    // otherwise choose the first matching candidate.
}

The above pseudo code is not intended to contain all aspects of the deployment algorithm. Still, it provides a useful glimpse of the overall process. This algorithm appears simple at first glance, but it is actually somewhat complex. This is due to the nature of deploying independently developed bundles. For example, in an ideal world, if an update for a bundle is made available, then updates for all of the bundles satisfying its dependencies are also made available. Unfortunately, this may not be the case, thus the deployment algorithm might have to install new bundles during an update to satisfy either new dependencies or updated dependencies that can no longer be satisfied by existing local bundles. In response to this type of scenario, the OBR deployment algorithm tries to favor updating existing bundles, if possible, as opposed to installing new bundles to satisfy dependencies. This approach is described in the {{findResolvingBundle(){{ method in the pseudo code above.

From the user's perspective, OBR's functionality is accessed indirectly, since OBR is a service API and not a user interface. For interactive access to OBR, a command is provided for Felix' shell service; this command service is accessible via shell server user interfaces, such as Felix' text-based or GUI-based shells. The OBR shell command is discussed below, but first the bundle metadata is described in the next section.

Bundle Metadata

OBR uses an XML-based repository file of bundle meta-data. The meta-data can be divided into three groups: required, human readable, and not currently used.

The following meta-data attributes are required by OBR for its functionality:

  • Bundle-SymbolicName - A generally unique name for the bundle, typically following the reverse domain name naming scheme.
  • Bundle-Version - The version of the bundle in the form of x.y.z.foo, where only x.y.z are significant and anything else is ignored. Only one version attribute per bundle is allowed.
  • Import-Package - An import package declaration for the bundle; specifies the package name and version. Zero or more import package attributes are allowed.
  • Export-Package - An export package declaration for the bundle; specifies the package name and version. Zero or more export package attributes are allowed.
  • Bundle-SourceURL - A URL from which the bundle's source code archive can be retrieved. Only one source URL attribute per bundle is allowed.

The following meta-data attributes are for human consumption:

  • Bundle-Name - The name of the bundle; this should be semi-unique, but it need not be. Only one name attribute per bundle is allowed.
  • Bundle-Description - A single-line description of the bundle's purpose. Only one description attribute per bundle is allowed.
  • Bundle-Category - A general category for the type of functionality provided by the bundle. Current categories are:
    • shell command
  • Bundle-LicenseURL - A URL pointing to the bundle license. At most one license URL attribute per bundle is allowed.
  • Bundle-DocURL - A URL pointing to full documentation for the bundle. At most one documentation URL attribute per bundle is allowed.
  • Bundle-Vendor - The name of the bundle creator. At most one vendor attribute per bundle is allowed.
  • Bundle-ContactAddress - An email address for point of contact for the bundle. At most one contact address attribute per bundle is allowed.
  • Bundle-Copyright - The copyright notice for the bundle. At most one copyright attribute per bundle is allowed.

The following meta-data attributes are not currently used, although future versions of OBR may use of them:

  • DynamicImport-Package - A dymanic import package declaration.
  • Import-Service - An imported service declaration. The format of this attribute is not defined yet.
  • Export-Service - An exported service declaration. The format of this attribute is not defined yet.
  • Bundle-RequiredExecutionEnvironment - Declares the bundle's execution environment requirements. The format of this attribute is not defined yet.
  • Bundle-NativeCode - Declares the bundle's native code requirements. The format of this attribute is not defined yet.

The following XML snippet shows the meta-data for OBR itself:

<bundle>
    <bundle-name>Bundle Repository</bundle-name>
    <bundle-description>
        A bundle repository service for Oscar.
    </bundle-description>
    <bundle-version>1.0.0</bundle-version>
    <bundle-updatelocation>
        http://oscar-osgi.sf.net/repo/bundlerepository/bundlerepository.jar
    </bundle-updatelocation>
    <bundle-sourceurl>
        http://oscar-osgi.sf.net/repo/bundlerepository/bundlerepository-src.jar
    </bundle-sourceurl>
    <bundle-docurl>
        http://oscar-osgi.sourceforge.net/repo/bundlerepository/index.html
    </bundle-docurl>
    <bundle-category>General</bundle-category>
    <import-package package="org.osgi.framework"/>
    <import-package package="org.ungoverned.osgi.service.shell"
        specification-version="1.0.0"/>
    <export-package package="org.ungoverned.osgi.service.bundlerepository"
        specification-version="1.0.0"/>
</bundle>

OBR Shell Command

Besides providing a service API, OBR implements a Felix shell command for accessing its functionality. For the end user, the OBR shell command is accessed using the text-based or GUI-based user interfaces for Felix' shell service. This section describes the syntax for the OBR shell command.

obr help

Syntax:

obr help [urls | list | info | install | deploy | start | update | source]

This command is used to display additional information about the other OBR commands.

obr list-url

Syntax:

obr urls [<repository-file-url> ...]

This command gets or sets the URLs to the repository files used by OBR. If no arguments are specified, then the current repository URLs are retrieved. Specify a space-delimited list of URLs to change the repository URLs. Each URL should point to a file containing meta-data about available bundles in XML format. The default repository file URL is http://oscar-osgi.sf.net/repo/repository.xml. You can also change the default repository URLs by defining the obr.repository.url property and giving it the value that you desire; the Oscar usage document describes how to configure bundle properties.

obr add-url

obr remove-url

obr list

Syntax:

obr list [<string> ...]

This command lists bundles available in the bundle repository. If no arguments are specified, then all available bundles are listed, otherwise any arguments are concatenated with spaces and used as a substring filter on the bundle names.

obr info

Syntax:

obr info <bundle-name>[;<version>] ...

This command displays the meta-data for the specified bundles. If a bundle's name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:

obr info "Bundle Repository";1.0.0

The above example retrieves the meta-data for version "1.0.0" of the bundle named "Bundle Repository".

obr deploy

Syntax:

obr deploy [-nodeps] <bundle-name>[;<version>] ... | <bundle-id> ...

This command tries to install or update the specified bundles and all of their dependencies by default; use the "-nodeps" switch to ignore dependencies. You can specify either the bundle name or the bundle identifier. If a bundle's name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:

obr deploy "Bundle Repository";1.0.0

For the above example, if version "1.0.0" of "Bundle Repository" is already installed locally, then the command will attempt to update it and all of its dependencies; otherwise, the command will install it and all of its dependencies.

obr start

Syntax:

obr start [-nodeps] <bundle-name>[;<version>] ...

This command installs and starts the specified bundles and all of their dependencies by default; use the "-nodeps" switch to ignore dependencies. If a bundle's name contains spaces, then it must be surrounded by quotes. If a specified bundle is already installed, then this command has no effect. It is also possible to specify a precise version if more than one version exists, such as:

obr start "Bundle Repository";1.0.0

The above example installs and starts the "1.0.0" version of the bundle named "Bundle Repository" and its dependencies.

obr source

Syntax:

obr source [-x] <local-dir> <bundle-name>[;<version>] ...

This command retrieves the source archives of the specified bundles and saves them to the specified local directory; use the "-x" switch to automatically extract the source archives. If a bundle name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:

obr source /home/rickhall/tmp "Bundle Repository";1.0.0

The above example retrieves the source archive of version "1.0.0" of the bundle named "Bundle Repository" and saves it to the specified local directory.

Using OBR with a Proxy

If you use a proxy for Web access, then OBR will not work for you in its default configuration; certain system properties must be set to enable OBR to work with a proxy. These properties are:

  • http.proxyHost - the name of the proxy host.
  • http.proxyPort - the port of the proxy host.
  • http.proxyAuth - the user name and password to use when connecting to the proxy; this string should be the user name and password separated by a colon (e.g., rickhall:mypassword).

These system properties can be set directly on the command line when starting the JVM using the standard "-D<prop>=<value>" syntax or you can put them in the lib/system.properties file of your Oscar installation; see documentation on configuring Oscar for more information.

Bundle Source Packaging

Coming soon...

Feedback

Feedback

Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org.

  • No labels