The Gogo Command bundle registers a set of commands for the interaction with the OBR service. Those commands allow registering repositories, listing their bundles, and requesting their download and installation.
Let's look at those commands in detail.
The obr:repos
command (repos for short, when there are no name conflicts) allows us to manage the repositories of the OBR service.
Its usage is as follows:
g! help repos
repos - manage repositories
scope: obr
parameters:
String ( add | list | refresh | remove )
String[] space-delimited list of repository URLs
The repos add
operation is used to register repositories with the OBR service. For example, let's register our releases repository:
g! repos add file:///C:/projects/felixbook/releases/repository.xml
Registered repositories are not kept between restarts of the framework. To have repositories automatically registered at startup, set the property obr.repository.url
in the framework conf/config.properties
file. Its value is a space-separated list of repository URLs.
For example, the default value for this property is the Felix releases repository:
obr.repository.url=http://felix.apache.org/obr/releases.xml
The repos remove
operation unregisters a previously added repository.
The repos list
operation is used to list the registered repositories, for example:
g! repos list
file:/C:/projects/felixbook/releases/repository.xml
http://felix.apache.org/obr/releases.xml
Here we have the default repository and the one we've just added.
The repos refresh
operation will reload the repositories that are passed as a parameter.
The obr:list
command finds bundles in the registered repositories and displays them. The search may be constrained by a filter on bundle names.
Its usage is as follows:
g! help list
list - list repository resources
scope: obr
flags:
-v, --verbose display all versions
parameters:
String[] optional strings used for name matching
The -v
(or --verbose)
flag is used to display more information on each bundle, including all versions and the bundle-symbolic name.
For example, the following lists the bundles in the repository containing the sub-string book
and displays verbose information:
g! list -v book
Bookshelf Inventory API
[com.packtpub.felix.bookshelf-inventory-api] (1.4.0)
Bookshelf Inventory Impl - Mock
[com.packtpub.felix.bookshelf-inventory-impl-mock] (1.4.0)
The output was reformatted for clarity.
The obr:info
command retrieves and displays the information available in the repository for one or more bundles.
The targeted bundles are passed as a space-separated list, each entry specified by display name, symbolic name, or bundle ID.
g! help info
info - retrieve resource description from repository
scope: obr
parameters:
String[] ( <bundle-name>
| <symbolic-name>
| <bundle-id>
)[@<version>
] ...
For example, the following is the repository information of the "Apache Felix Gogo Shell Runtime" (bundle ID 3):
g! obr:info 3
-------------------------------
Apache Felix Gogo Shell Runtime
-------------------------------
license: http://www.apache.org/licenses/LICENSE-2.0.txt
symbolicname: org.apache.felix.gogo.runtime
uri: http://repo1.maven.org/maven2/org/apache/felix/gogo/-
org.apache.felix.gogo.runtime/0.2.0/-
org.apache.felix.gogo.runtime-0.2.0.jar
documentation: http://www.apache.org/
category: [org.apache.felix.gogo]
description: Apache Felix Gogo Shell
size: 58198
presentationname: Apache Felix Gogo Shell Runtime
id: org.apache.felix.gogo.runtime/0.2.0
version: 0.2.0
Requires:
(&(package=org.osgi.framework))
(&(package=org.osgi.service.command)(version>=0.2.0))
(&(package=org.osgi.service.packageadmin))
(&(package=org.osgi.service.threadio)(version>=0.2.0))
(&(package=org.osgi.util.tracker))
Capabilities:
{manifestversion=2, symbolicname=org.apache.felix.gogo.runtime,
presentationname=Apache Felix Gogo Shell Runtime, version=0.2.0}
{package=org.osgi.service.command, version=0.2.0}
{package=org.osgi.service.threadio, version=0.2.0}
The obr:deploy
command is used to download bundles from the repository and install them onto the Felix instance, with the possibility of optionally starting them.
The command usage is as follows:
g! help deploy
deploy - deploy resource from repository
scope: obr
flags:
-s, --start start deployed bundles
parameters:
String[] ( <bundle-name>
| <symbolic-name> | <bundle-id> )[@<version>] ...
The -s
(or --start)
flag is used to request the start of the bundles that were just installed.
We will use this command in a short while to install and start our Book Inventory API and implementation bundles.
The obr:source
and obr:javadoc
commands are used to download a bundle's sources and JavaDocs
archives (if present) to a local directory, and to optionally extract them.
The targeted bundles are specified as a space-separated list of references, each reference being the bundle-symbolic name, presentation name, or ID, with an optional version specification.
The obr:source
and obr:javadoc
commands have similar usage. The following command is that of the javadoc:
g! help javadoc
javadoc - retrieve resource JavaDoc from repository
scope: obr
flags:
-x, --extract extract documentation
parameters:
File local target directory
String[] ( <bundle-name>
| <symbolic-name>
| <bundle-id>
)[@<version>
] ...
The -x
(or --extract)
flag is used to request that the archive be extracted once it is downloaded.
As you go through your development cycle, you'll need to refresh the bundles on your framework with their latest versions for testing.
The obr:refresh
command reloads the repository listing from its source and updates the list of available bundles. However, this does not mean that the bundles have been refreshed. For this, you'll need to update
the bundle.
The full cycle at each rebuild of a bundle (assuming you're using the same version) would be as follows:
obr:refresh
command:-> repos refresh file:/C:/projects/felixbook/releases/repository.
xml
felix:update <id>
command.This command finds the latest version of the bundle and installs it. If the bundle was previously started, it will be restarted after the installation.
Updating a bundle may not work as well as expected if the installation failed because classes were not found. In those cases, it's better to uninstall and then deploy it again.
You will find yourself going through this cycle often. Alternatively, you can use a direct file install using the felix:install
command and then update the bundle using the felix:update
command. This is useful for fast deploy-test cycles re-using the same version of the bundle.