felix-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Felix Meschberger <fmesc...@gmail.com>
Subject Re: [CONF] Apache Felix: Apache Felix OSGi Bundle Repository OBR (page edited)
Date Thu, 11 Sep 2008 06:21:08 GMT
Hi,

Richard S. Hall schrieb:
> If we are going to edit the page to not have parentheses, then we might
> as well get rid of the "OBR" too since it doesn't really make sense the
> way it is now without them...

Agreed.

But if I had removed it completely, the URL would have changed. And this
I considered a bigger problem, especially since the URL is also referred
to in the bundlerepository bundle.


On the other hand this title is visible in two places AFAICT: The window
title of the browser and in the table of contents of the Subproject
Documentation page. Both are generated automatically from the page name.


WDYT ?

Regards
Felix

> 
> -> richard
> 
> 
> confluence@apache.org wrote:
>> Page Edited : FELIX <http://cwiki.apache.org/confluence/display/FELIX>
>> : Apache Felix OSGi Bundle Repository OBR
>> <http://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+OSGi+Bundle+Repository+OBR>
>>
>>
>> Apache Felix OSGi Bundle Repository OBR
>> <http://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+OSGi+Bundle+Repository+OBR>
>> has been edited by Felix Meschberger
>> <http://cwiki.apache.org/confluence/display/%7Efmeschbe> (Sep 10, 2008).
>>
>> Change summary:
>>
>> Remove brackets from page name
>>
>> (View changes)
>> <http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=7950&originalVersion=15&revisedVersion=16>
>>
>>
>> Content:
>>
>>
>>   Apache Felix OSGi Bundle Repository (OBR)
>>
>>     * Motivation <#ApacheFelixOSGiBundleRepositoryOBR-Motivation>
>>     * Overview <#ApacheFelixOSGiBundleRepositoryOBR-Overview>
>>     * OBR Repository File
>>       <#ApacheFelixOSGiBundleRepositoryOBR-OBRRepositoryFile>
>>     * OBR Service API <#ApacheFelixOSGiBundleRepositoryOBR-OBRServiceAPI>
>>     * OBR Shell Command
>>       <#ApacheFelixOSGiBundleRepositoryOBR-OBRShellCommand>
>>           o obr help
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrhelp%7D%7D>
>>           o obr list-url
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrlisturl%7D%7D>
>>           o obr add-url
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobraddurl%7D%7D>
>>           o obr remove-url
>>            
>> <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrremoveurl%7D%7D>
>>           o obr list
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrlist%7D%7D>
>>           o obr info
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrinfo%7D%7D>
>>           o obr deploy
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrdeploy%7D%7D>
>>           o obr start
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrstart%7D%7D>
>>           o obr source
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrsource%7D%7D>
>>           o obr javadoc
>>             <#ApacheFelixOSGiBundleRepositoryOBR-%7B%7Bobrjavadoc%7D%7D>
>>     * Using OBR with a Proxy
>>       <#ApacheFelixOSGiBundleRepositoryOBR-UsingOBRwithaProxy>
>>     * Bundle Source Packaging
>>       <#ApacheFelixOSGiBundleRepositoryOBR-BundleSourcePackaging>
>>     * Note on OSGi R3 Bundles
>>       <#ApacheFelixOSGiBundleRepositoryOBR-NoteonOSGiR3Bundles>
>>     * Feedback <#ApacheFelixOSGiBundleRepositoryOBR-Feedback>
>>
>>
>>     Motivation
>>
>> 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 meta-data file for your local bundles; see the obr
>> list-url, obr add-url, and obr remove-url commands for more details.
>>
>>
>>     Overview
>>
>> For the most part, OBR is quite simple. An OBR "repository server" is
>> not necessary, since all functionality may reside on the client side.
>> OBR is able to provide 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. From the meta-data, OBR is able to construct
>> dependency information for deploying (i.e., installing and updating)
>> bundles.
>>
>> OBR defines the following entities:
>>
>>     * /*Repository Admin*/ - a service to access a federation of
>>       repositories.
>>     * /*Repository*/ - provides access to a set of resources.
>>     * /*Resource*/ - a description of an artifact to be installed on a
>>       device.
>>     * /*Capability*/ - a named set of properties.
>>     * /*Requirement*/ - an assertion on a capability.
>>     * /*Resolver*/ - an object to resolve resource dependencies and to
>>       deploy them.
>>     * /*Repository file*/ - XML file containing resource meta-data.
>>
>> The following diagram illustrates the relationships among these entities:
>>
>> The client has access to a federated set of repositories via the
>> Repository Admin service; such as depicted in this view:
>>
>>
>>     OBR Repository File
>>
>> The OBR repository file is an XML-based representation of bundle
>> meta-data. The goal is provide a generic model for describing
>> dependencies among resources; as such, the term /*resource*/ is used
>> instead of /*bundle*/ in the OBR repository syntax; a detailed
>> description of the OBR meta-data format is available in the OSGi RFC
>> 112^ <http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf>
>> document; this document is not completely in sync with the
>> implementation, but the concepts are still correct. The following XML
>> snippet depicts the overall structure of a repository file:
>>
>> <repository presentationname="..." symbolicname="..." ... >
>>     <resource>
>>         <description>...</description>
>>         <size>...</size>
>>         <documentation>...</documentation>
>>         <source>...</source>
>>         <category id="..."/>
>>         <capability>...</capability>
>>         ...
>>         <requirement>...</requirement>
>>         ...
>>     </resource>
>>     ...
>> </repository>
>>        
>> The above repository defines a set of available resources, each
>> described by a set of meta-data. Some resource meta-data is purely
>> intended for human consumption; the most important aspects relate to
>> the generic capability/requirement model.
>>
>> A resource can provide any number of capabilities. A capability is a
>> typed set of properties. For example, the following is an exported
>> package capability:
>>
>> <capability name='package'>
>>     <p n='package' v='org.foo.bar'/>
>>     <p n='version' t='version' v='1.0.0'/>
>> </capability>
>>        
>> This capability is of type 'package' and exports 'org.foo.bar' at
>> version '1.0.0'. Conversely, a requirement is a typed LDAP query over
>> a set of capability properties. For example, the following is an
>> imported package requirement:
>>
>> <require name='package' extend='false'
>>     multiple='false' optional='false'
>>     filter='(&amp;(package=org.foo.bar)(version&gt;=1.0.0))'>
>>     Import package org.foo.bar
>> </require>
>>        
>> This requirement is of type 'package' and imports 'org.foo.bar' at
>> versions greater than '1.0.0'. Although this syntax looks rather
>> complicated with the '\&' and '\>=' syntax, it is simply the standard
>> OSGi LDAP query syntax in XML form (additionally, Peter Kriens has
>> created a tool called bindex to generate this meta-data from a
>> bundle's manifest).
>>
>> With this generic dependency model, OBR is able to provide mappings
>> for the various OSGi bundle dependencies; e.g., import/export package,
>> provide/require bundle, host/fragment, import/export service,
>> execution environment, and native code. In addition, it is possible
>> for bundles to introduce arbitrary dependencies for custom purposes.
>>
>> Two other 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.
>>
>>
>>     OBR Service API
>>
>> Typically, OBR service clients only need to interact with the
>> Repository Admin service, which provides the mechanisms necessary to
>> discover available resources. The Repository Admin interface is
>> defined as follows:
>>
>> public interface RepositoryAdmin
>> {
>>     public Resource[] discoverResources(String filterExpr);
>>     public Resolver resolver();
>>     public Repository addRepository(URL repository)?
>>         throws Exception;
>>     public boolean removeRepository(URL repository);
>>     public Repository[] listRepositories();
>>     public Resource getResource(String respositoryId);
>> }
>>
>> In order to resolve and deploy available resources, the Repository
>> Admin provides Resolver instances, which are defined as follows:
>>
>> public interface Resolver
>> {
>>     public void add(Resource resource);
>>     public Requirement[] getUnsatisfiedRequirements();
>>     public Resource[] getOptionalResources();
>>     public Requirement[] getReason(Resource resource);
>>     public Resource[] getResources(Requirement requirement);
>>     public Resource[] getRequiredResources();
>>     public Resource[] getAddedResources();
>>     public boolean resolve();
>>     public void deploy(boolean start);
>> }
>>
>> When desired resources are discovered via the query mechanisms of the
>> Repository Admin, they are added to a Resolver instance which will can
>> be used to resolve all transitive dependencies and to reflect on any
>> resolution result. The following code snippet depicts a typical usage
>> scenario:
>>
>> RepositoryAdmin repoAdmin = ... // Get repo admin service
>> Resolver resolver = repoAdmin.resolver();
>> Resource resource = repoAdmin.discoverResources(filterStr);
>> resolver.add(resource);
>> if (resolver.resolve())
>> {
>>     resolver.deploy(true);
>> }
>> else
>> {
>>     Requirement[] reqs = resolver.getUnsatisfiedRequirements();
>>     for (int i = 0; i < reqs.length; i++)
>>     {
>>         System.out.println("Unable to resolve: " + reqs[i]);
>>     }
>> }
>>
>> This code gets the Repository Admin service and then gets a Resolver
>> instance from it. It then discovers an available resource and adds it
>> to the resolver. Then it tries to resolve the resources dependencies.
>> If successful it deploys the resource to the local framework instance;
>> if not successful it prints the unsatisfied requirements.
>>
>> OBR's deployment algorithm appears simple at first glance, but it is
>> actually somewhat complex 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.
>>
>> In the general case, OBR user's will not use the OBR API directly, but
>> will use its functionality indirectly from another tool or user
>> interface. For example, interactive access to OBR is available via a
>> command for Felix' shell service
>> </confluence/display/FELIX/Apache+Felix+Shell+Service>. The OBR shell
>> command is discussed in the next section.
>>
>>
>>     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 [add-url | remove-url | list-url | list | info | deploy |
>> start | source | javadoc]
>>        
>> This command is used to display additional information about the other
>> OBR commands.
>>
>>
>>       obr list-url
>>
>> Syntax:
>>
>> obr list-url
>>        
>> This command gets the URLs to the repository files used by the
>> Repository Admin.
>>
>>
>>       obr add-url
>>
>> Syntax:
>>
>> obr add-url [<repository-file-url> ...]
>>        
>> This command adds a repository file to the set of repository files for
>> which the Repository Admin service provides access. The repository
>> file is represented as a URL. If the repository file URL is already in
>> the Repository Admin's set of repository files, the request is treated
>> like a reload operation.
>>
>>
>>       obr remove-url
>>
>> Syntax:
>>
>> obr remove-url [<repository-file-url> ...]
>>        
>> This command removes a repository file to the set of repository files
>> for which the Repository Admin service provides access. The repository
>> file is represented as a 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 <bundle-name>[;<version>] ... | <bundle-id> ...
>>        
>> This command tries to install or update the specified bundles and all
>> of their dependencies by default. 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.
>>
>>
>>       obr javadoc
>>
>> Syntax:
>>
>> obr javadoc [-x] <local-dir> <bundle-name>[;<version>] ...
>>        
>> This command retrieves the javadoc archives of the specified bundles
>> and saves them to the specified local directory; use the "-x" switch
>> to automatically extract the javadoc 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 javadoc /home/rickhall/tmp "Bundle Repository";1.0.0
>>        
>> The above example retrieves the javadoc 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 Felix
>> installation; see documentation on configuring Felix for more
>> information.
>>
>>
>>     Bundle Source Packaging
>>
>> Coming soon...
>>
>>
>>     Note on OSGi R3 Bundles
>>
>> In contrast to OSGi R4 the previous specifications, most notably R3,
>> allowed bundles without the Bundle-SymbolicName header. The Felix OSGi
>> Bundle Repository implementation heavily relies on the symbolic name
>> being defined in bundles. As a consequence bundles without a symbolic
>> name are not fully supported by the Bundle Repository:
>>
>>     * Bundles installed in the framework are used by the Bundle
>>       Repository implementation to resolve dependencies regardless of
>>       whether they have a Bundle-SymbolicName header or not.
>>       Resolution of dependencies against the installed bundles takes
>>       place based on the Export-Package headers.
>>     * Bundles installed in the framework without a Bundle-SymbolicName
>>       header cannot be updated by the Bundle Repository implementation
>>       because updates from the bundle repository cannot be correlated
>>       to such "anonymous" bundles.
>>
>>
>>     Feedback
>>
>> Subscribe to the Felix users mailing list by sending a message to
>> users-subscribe@felix.apache.org^
>> <mailto:users-subscribe@felix.apache.org>; after subscribing, email
>> questions or feedback to users@felix.apache.org^
>> <mailto:users@felix.apache.org>.
>>
>> Powered by Atlassian Confluence
>> <http://www.atlassian.com/software/confluence/default.jsp?clicked=footer>
>> (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request
>> <http://jira.atlassian.com/secure/BrowseProject.jspa?id=10470>
>>
>> Unsubscribe or edit your notifications preferences
>> <http://cwiki.apache.org/confluence/users/viewnotifications.action>
> 

Mime
View raw message