One of the many powerful features of Felix (and OSGi-compliant applications in general) is that many actions can be applied on bundles without needing to restart the framework. Bundles can be installed, updated, uninstalled, and so on while the remaining functionality of the framework is active.
The following are some of the available commands and a description of their usage. We will get to use many of those as we go along, so you need not worry much about learning them by heart. Just know they exist.
One of the most frequently used shell commands is the list bundles command (lb), which gives a listing of the currently installed bundles, showing some information on each of them.
Let's check what's running on our newly installed framework:
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (3.0.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.2)
2|Active | 1|Apache Felix Gogo Command (0.6.0)
3|Active | 1|Apache Felix Gogo Runtime (0.6.0)
4|Active | 1|Apache Felix Gogo Shell (0.6.0)
The listing provides the following useful information about each bundle:
- Each bundle is given a unique
idon install— this ID is used by commands such asupdateoruninstallto apply actions on that bundle - The bundle's lifecycle
state, which we've introduced in Chapter 1, Quick intro to Felix and OSGi - The bundle's start level
- The bundle's
nameandversion
This command also takes a parameter for filtering the bundles list. For example, to include only bundles that have 'bundle' in their name:
g! lb bundle
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (3.0.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.2)
The help command provides hints on the usage of commands.
When called without any parameters, the help command gives a listing of the available commands:
g! help
felix:bundlelevel
felix:cd
felix:frameworklevel
felix:headers
felix:help
felix:inspect
felix:install
felix:lb
felix:log
felix:ls
felix:refresh
felix:resolve
felix:start
felix:stop
felix:uninstall
felix:update
felix:which
gogo:cat
gogo:each
gogo:echo
gogo:format
gogo:getopt
gogo:gosh
gogo:grep
gogo:not
gogo:set
gogo:sh
gogo:source
gogo:tac
gogo:telnetd
gogo:type
gogo:until
obr:deploy
obr:info
obr:javadoc
obr:list
obr:repos
obr:source
We'll cover the felix scope commands here and some of the gogo scope commands in the next section. The obr scope commands will be covered later, in Chapter 6,Using the OSGi Bundle Repository.
More help on the syntax of each command can be requested by typing help <command-name>.
For example, for more help on the repos command:
g! help repos
repos - manage repositories
scope: obr
parameters:
String ( add | list | refresh | remove )
String[] space-delimited list of repository URLs
When the command is available with multiple signatures, a help block per signature is provided, for example:
g! help help
help - displays information about a specific command
scope: felix
parameters:
String target command
help - displays available commands
scope: felix
Here, the help command has 2 syntaxes: one that takes a parameter (the target command), and another that takes no parameters. We've used the first one to get help on help.
The install command is used to instruct Felix to install an external bundle. The syntax is as follows:
g! help install
install - install bundle using URLs
scope: felix
parameters:
String[] target URLs
Each bundle is located using the URL and is downloaded to the local cache for installation.
Once a bundle is installed, it is given a unique id. This ID is used to refer to this bundle when using commands such as update or uninstall. For example:
g! install http://www.mysite.com/testbundle-1.0.0.jar
Bundle ID: 7
Here, the bundle I've just installed has the ID 7.
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (3.0.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.2)
2|Active | 1|Apache Felix Gogo Command (0.6.0)
3|Active | 1|Apache Felix Gogo Runtime (0.6.0)
4|Active | 1|Apache Felix Gogo Shell (0.6.0)
7|Installed | 1|Test Bundle (1.0.0)
In cases where many bundles are to be installed from the same base URL, you may want to set a session variable with the common base URL to simplify the task.
For example, instead of executing:
g! install http://site.com/bundle1.jar http://site.com/bundle2.jar
g! b = http://site.com
g! install $b/bundle1.jar $b/bundle2.jar
As newer versions of bundles are released, it is easy to update the installed bundle with a newer version by using the update command.
The update command takes a bundle ID and an optional source URL as parameters. Its syntax is:
g! help update
update - update bundle
scope: felix
parameters:
Bundle target bundle
update - update bundle from URL
scope: felix
parameters:
Bundle target bundle
String URL from where to retrieve bundle
For example:
g! update 7 http://www.mysite.com/testbundle-1.0.1.jar
g!
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (3.0.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.2)
2|Active | 1|Apache Felix Gogo Command (0.6.0)
3|Active | 1|Apache Felix Gogo Runtime (0.6.0)
4|Active | 1|Apache Felix Gogo Shell (0.6.0)
7|Installed | 1|Test Bundle (1.0.1)
Notice that the bundle ID remains unchanged.
When a source URL is not provided, the bundle is updated from the same location it was installed from.
The resolve command requests that the framework undergo the resolution process for the given bundle. Refer to Chapter 1 for a review of the bundle life-cycle stages.
The syntax of this command is as follows:
g! help resolve
resolve - resolve bundles
scope: felix
parameters:
Bundle[] target bundles (can be null or empty)
If no parameter is provided, then the framework will resolve all unresolved bundles. To resolve specific bundles, the list ids of the bundles to be resolved are passed as parameters.
The stop and start commands take a space-separated sequence of bundle IDs to stop or to start (refer to Chapter 1 for more on the lifecycle of a bundle).
The stop command syntax is as follows:
g! help stop
stop - stop bundles
scope: felix
flags:
-t, --transient stop bundle transiently
parameters:
Bundle[] target bundles
Use the -t (or --transient) flag to stop the bundle in transient mode, that is, not saving its state to the persisted auto-start state. The framework will not remember this bundle as having been stopped the next time it is restarted.
The start command syntax is similar to the stop command:
g! help start
start - start bundles
scope: felix
flags:
-p, --policy use declared activation policy
-t, --transient start bundle transiently
parameters:
String[] target bundle identifiers or URLs
It uses the -t flag in the same way as the stop command.
Use the -p (of --policy) flag to use the activation policy declared in the Bundle-ActivationPolicy header.
The uninstall command is used to remove one or more bundles from the framework. The bundles are first stopped and then uninstalled.
The usage of this command is as follows:
g! help uninstall
uninstall - uninstall bundles
scope: felix
parameters:
Bundle[] target bundles
The list of IDs of bundles to be uninstalled is passed as a parameter.
The refresh command forces the update of the packages exported by the refreshed bundles. The refresh is performed to the provided bundles and the bundles that depend on them. It is typically used after an update or after an uninstall of a bundle, to update the packages exported by an updated bundle and to completely remove those of an uninstalled one.
The syntax of the refresh command is as follows:
g! help refresh
refresh - refresh bundles
scope: felix
parameters:
Bundle[] target bundles (can be null or empty)
To refresh specific bundles, the ids of those bundles are passed as parameters. Otherwise, calling refresh with no parameters refreshes all bundles that were updated or uninstalled.
The headers and inspect commands provide valuable information on how a bundle is perceived by the framework. The headers command lists the bundle headers in the main section of the bundle's manifest. Its usage is as follows:
g! help headers
headers - display bundle headers
scope: felix
parameters:
Bundle[] target bundles
For example, to display the headers of the bundle Apache Felix Bundle Repository, use:
g! headers 1
Apache Felix Bundle Repository (1)
----------------------------------
Bnd-LastModified = 1272565441581
Build-Jdk = 1.6.0_17
Built-By = gnodet
Bundle-Activator = org.apache.felix.bundlerepository.impl.Activator
Bundle-Description = Bundle repository service.
Bundle-DocURL = http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html
Bundle-License = http://www.apache.org/licenses/LICENSE-2.0.txt
Bundle-ManifestVersion = 2
Bundle-Name = Apache Felix Bundle Repository
Bundle-Source = http://felix.apache.org/site/downloads.cgi
Bundle-SymbolicName = org.apache.felix.bundlerepository
Bundle-Url = http://felix.apache.org/site/downloads.cgi
Bundle-Vendor = The Apache Software Foundation
Bundle-Version = 1.6.2
Created-By = Apache Maven Bundle Plugin
...
The inspect command displays various information on a bundle's dependencies, requirements, packages it exports, and so on. Its usage is as follows:
g! help inspect
inspect - inspects bundle dependency information
scope: felix
parameters:
String (package | bundle | fragment | service)
String (capability | requirement)
Bundle[] target bundles
The first parameter is the inspection type:
packageto inspect package-related information, for example, which packages the specified bundles import from or export to other bundlesbundleto inspect the requirements or capabilities of the given bundlesfragmentto inspect fragment-related information, such as a fragment's host or the list of hosted fragmentsserviceto inspect the bundles service related information, such as the list of imported or exported services
The second parameter is the direction of the inspection, with respect to the bundle:
capabilityto inspect what the specified bundles can give to the platformrequirementto inspect what the specified bundles need from the platform
The remaining parameters are one or more bundles to be inspected.
For example, the package capability of the bundle Apache Felix Bundle Repository are as follows:
g! inspect package capability 1
org.apache.felix.bundlerepository [1] exports packages:
-------------------------------------------------------
org.apache.felix.bundlerepository; version=2.0.0 imported by:
org.apache.felix.gogo.command [2]
This says that the bundle exports a package (org.apache.felix.bundlerepository), which is imported by bundle 2, Apache Felix Gogo Command.
The which command will provide information on where a given bundle loads a given class. This command is useful when investigating problems related to conflicts between classes or issues with their visibility.
Its syntax is as follows:
g! help which
which - determines from where a bundle loads a class
scope: felix
parameters:
Bundle target bundle
String target class name
The first parameter is the bundle to use as the context for the class loading and the second is the name of the class to load.
For example, to know where the bundle Apache Felix Gogo Command loads its org.apache.felix.bundlerepository.Repository class, use:
g! which 2 org.apache.felix.bundlerepository.Repository
Loaded from: org.apache.felix.bundlerepository [1]
The answer is bundle 1: Apache Felix Bundle Repository. The result shows the bundle symbolic name and the bundle ID.
The log command allows us to peek into the list of the last few log entries. Its usage is as follows:
g! help log
log - display some matching log entries
scope: felix
parameters:
int maximum number of entries
String minimum log level [ debug | info | warn | error ]
log - display all matching log entries
scope: felix
parameters:
String minimum log level [ debug | info | warn | error ]
The default Felix distribution doesn't come with a log service installed, so running this command at this point will issue a warning:
g! log debug
Log reader service is unavailable.
We will install one in Chapter 10, Improving the Logging, when we add proper logging to our case study and also cover its usage in more details at that point.
Some of the commands that are available through this console may read from or write to files. For example, the grep command can read a file and display the lines that match a given pattern. It will read the file relative to the shell session working directory. We will look at this and other file manipulating commands in a short while.
The cd and ls commands are very similar to their Unix counterparts.
The cd command is used to display or change the current shell working directory. Its usage is as follows:
g! help cd
cd - change current directory
scope: felix
parameters:
CommandSession automatically supplied shell session
String target directory
cd - get current directory
scope: felix
parameters:
CommandSession automatically supplied shell session
When called without parameters, it will display the current working directory. To change the current directory, pass the target directory as a parameter.
The ls command is used to list the contents of a directory. Its syntax is as follows:
g! help ls
ls - get specified path contents
scope: felix
parameters:
CommandSession automatically supplied shell session
String path with optionally wild carded file name
ls - get current directory contents
scope: felix
parameters:
CommandSession automatically supplied shell session
The path of the directory to be listed is passed as a parameter. If no parameters are passed, then the contents of the current working directory are shown.
For example, the contents of the current directory are as follows:
g! ls
C:felixin
C:felixundle
C:felixconf
C:felixDEPENDENCIES
C:felixdoc
C:felixfelix-cache
C:felixLICENSE
C:felixLICENSE.kxml2
C:felixNOTICE
C:felix
un.bat
Changing to a sub-directory:
g! cd bundle
Name bundle
CanonicalPath C:felixundle
Parent C:felix
Path C:felixundle
AbsoluteFile C:felixundle
AbsolutePath C:felixundle
CanonicalFile C:felixundle
ParentFile C:felix
In Chapter 1, we've covered the start level of the framework and bundles. The frameworklevel and bundlelevel commands allow us to modify those start levels.
The frameworklevel command is used to get or set the framework's active start level. Its syntax is as follows:
g! help frameworklevel
frameworklevel - query framework active start level
scope: felix
frameworklevel - set framework active start level
scope: felix
parameters:
int target start level
To get the active start level of the framework, use the command without any parameters:
g! frameworklevel
Level is 1
To change it, pass the target start level as a parameter.
The bundle level displays and manipulates the bundle's start levels. Its syntax is:
g! help bundlelevel
bundlelevel - set bundle start level or initial bundle start level
scope: felix
flags:
-i, --setinitial set the initial bundle start level
-s, --setlevel set the bundle's start level
parameters:
int target level
Bundle[] target identifiers
bundlelevel - query bundle start level
scope: felix
parameters:
Bundle bundle to query
To query the start level of a bundle, use the command with one parameter the bundle ID:
g! bundlelevel 2
org.apache.felix.gogo.command [2] is level 1
To change the framework's initial bundle start level, use the command with the option -i set:
g! bundlelevel -i 2
This has set the initial bundle start level to 2 for newly installed bundles.
To change the start level of one or more bundles, use the -s option followed by the target start level and the list of bundles to modify.