Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A launcher, user interface, and bundle management agent for Apache Felix.

branch: master
Octocat-spinner-32 META-INF knapsack: preface commands with 'knapsack-' for cleaner system shell September 08, 2011
Octocat-spinner-32 org knapsack: update framework version to 4.0.2 December 19, 2011
Octocat-spinner-32 scripts knapsack: build with line numbers in jar for debugging, add launcher August 12, 2011
Octocat-spinner-32 tests knapsack: file cleanup, refactored filesystem commands to be dynamic. June 24, 2011
Octocat-spinner-32 .checkstyle knapsack: version bump for framework version. July 20, 2011
Octocat-spinner-32 .classpath knapsack: a new strategy for netcat client: by default use a separate July 25, 2011
Octocat-spinner-32 .gitignore knapsack: script cleanup August 07, 2011
Octocat-spinner-32 .project knapsack: added eclipse metadata May 15, 2011
Octocat-spinner-32 LICENSE-2.0.txt knapsack: applied apache 2.0 license headers to new source files. May 15, 2011
Octocat-spinner-32 README.markdown knapsack: updated readme to be more current with functionality, but August 29, 2011
Octocat-spinner-32 build.xml knapsack: refactor command prefix to be user configurable. Default to October 13, 2011
Octocat-spinner-32 configadmin.properties knapsack: allow variable substitution in property files. August 07, 2011
Octocat-spinner-32 felix.properties knapsack: allow variable substitution in property files. August 07, 2011
Octocat-spinner-32 felix.version knapsack: update framework version to 4.0.2 December 19, 2011
Octocat-spinner-32 knapsack.properties knapsack: update framework version to 4.0.2 December 19, 2011
Octocat-spinner-32 knapsack.version knapsack: update framework version to 4.0.2 December 19, 2011
Octocat-spinner-32 log.properties knapsack: remove ansi color feature due to inefficiency and added log August 15, 2011
README.markdown

Knapsack for Apache Felix

Knapsack is a custom launcher for the Apache Felix OSGi Framework with native shell integration and a few default services that run out of the box. See http://kgilmer.github.com/knapsack/ for more information about its design.

Setting up an OSGi-based application

$ mkdir test && cp knapsack.jar test/ && cd test
$ wget https://leafcutter.ci.cloudbees.com/job/knapsack/lastSuccessfulBuild/artifact/knapsack.jar
$ java -jar knapsack.jar &
[1] 5513
...
INFO: Framework started in 0.144 seconds with activators: [org.apache.felix.log.Activator@44bd928a, org.apache.felix.cm.impl.ConfigurationManager@79dfc547, org.knapsack.Activator@5210f6d3]
  • The core framework, Knapsack, the Log Service, and the Configuration Admin are now running. However, they do not show up as seperate bundles because they are run at startup with the framework itself. Take a look:
$ bin/bundles 
ACTIV   [ 0]org.apache.felix.framework (0.0.0)  Bundle
  • Now let's add some bundles to our running instance to add services and functionality. Knapsack automatically creates a directory for us to add bundles to:
$ cd bundle
$ wget http://ftp.jaist.ac.jp/pub/apache//felix/org.apache.felix.http.bundle-2.2.0.jar
$ wget http://ftp.jaist.ac.jp/pub/apache//felix/org.apache.felix.webconsole-3.1.8.jar
$ wget http://ftp.jaist.ac.jp/pub/apache//felix/org.apache.felix.webconsole.plugins.memoryusage-1.0.2.jar
$ wget http://ftp.jaist.ac.jp/pub/apache//felix/org.apache.felix.metatype-1.0.4.jar
$ wget http://ftp.jaist.ac.jp/pub/apache//felix/org.apache.felix.http.jetty-2.2.0.jar

This set of bundles will let us run servlets and expose the running framework via a web console. We need to tell knapsack to start the bundles, not just install them. We do this by setting the execution bit on the file:

$ chmod u+x *
  • Now we tell knapsack to rescan the bundle directory:
$ cd ..
$ bin/update
...

Knapsack now will look in the configured bundle directories for new or changed bundles. It will start/stop/install bundles accordingly.

  • You will see some exceptions in the output, but these are not critical and refer to some missing optional dependencies. You can confirm that the http server and web console are running with:
$ bin/bundles | grep ACT
ACTIV   [ 0]org.apache.felix.framework (0.0.0)  Bundle
ACTIV   [ 1]org.apache.felix.webconsole (3.1.8)     /tmp/kt/bundle/org.apache.felix.webconsole-3.1.8.jar
ACTIV   [ 2]org.apache.felix.webconsole.plugins.memoryusage (1.0.2)     /tmp/kt/bundle/org.apache.felix.webconsole.plugins.memoryusage-1.0.2.jar
ACTIV   [ 4]org.apache.felix.metatype (1.0.4)   /tmp/kt/bundle/org.apache.felix.metatype-1.0.4.jar
ACTIV   [ 5]org.apache.felix.http.jetty (2.2.0)     /tmp/kt/bundle/org.apache.felix.http.jetty-2.2.0.jar
ACTIV   [ 6]org.apache.felix.http.bundle (2.2.0)    /tmp/kt/bundle/org.apache.felix.http.bundle-2.2.0.jar

If you direct your web browser to http://localhost/system/console you should see the admin interface. Log in with admin/admin to inspect your runtime environment.

Felix Web Console

Directory Layout

Knapsack will create it's preferred configuration environment if it's not already provided. After running knapsack the directory should look something like this:

$ ls
bin  bundle  cache  configAdmin properties felix.conf  knapsack.jar

/bin

This is where the 'native' scripts are stored that can be executed via the system terminal. There is a hidden file .knapsack-command.sh which does the work of storing the randomly generated active port number (so that multiple knapsack instances do not collide), and passing the command line to knapsack via netcat.

/bundle

This is the default location where bundles are stored. As mentioned in felix.conf, you can set org.knapsack.bundleDirs to be any set of directories, scanned in the order they are specified.

Organizing an application is into logical areas of functionality, for example a web application could have core, database, and http directories, each with relevant bundles, making deployment a bit easier.

/cache

This is where the Felix bundle cache goes. It is an exploded form of the bundle jars. By default, this directory is deleted each time Knapsack runs, to ensure that the latest code from bundle directories is always getting executed.

/configadmin

Configuration Admin typically keeps its state in the bundle cache. We want to preserve configuration state across knapsack instances so we store it seperately.

/properties

Startup state can be set in Felix via system properties or Configuration Admin. Knapsack will load property files and Configuration Admin dictionaries from the default directory. Any file ending with ".properties" will be treated as a properties file, otherwise the filename will be assumed a PID and a Configuration will be created with its name/value pairs.

Since all files in this directory are properties, one can have different files for different services or bundles, rather than one giant property file. This also is nice for installers, when a set of properties corresponds to a bundle or aspect of functionality.

/properties/felix.properties

A default felix configuration is generated if it doesn't already exist. This lets the user tune the startup settings that are related to the framework internals.

/properties/knapsack.properties

The knapsack launcher-specific properties. These properties allow to enable/disable specific features and tune the shell integration with the local environment.

/properties/log.properties

The log properties. Set log verbosity here.

/properties/configadmin.properties

The ConfigAdmin properties. By default, simply specifying the persistence directory.

System shell features

Check the log with:

$ bin/log 
...
07.20 09:29:49  INFO        BundleEvent INSTALLED   [ 2]org.apache.felix.webconsole.plugins.memoryusage (1.0.2)
07.20 09:29:49  INFO        BundleEvent INSTALLED   [ 3]org.apache.felix.deploymentadmin (0.9.0)
07.20 09:29:49  INFO        BundleEvent INSTALLED   [ 4]org.apache.felix.metatype (1.0.4)
07.20 09:29:49  INFO        BundleEvent INSTALLED   [ 5]org.apache.felix.http.jetty (2.2.0)
...

Grep for errors:

$ bin/log | grep ERR
07.20 09:29:49  ERROR       FrameworkEvent ERROR    [ 3]org.apache.felix.deploymentadmin (0.9.0)
07.20 09:30:08  ERROR       Unable to start /tmp/kt/bundle/org.apache.felix.deploymentadmin-0.9.0.jar.  [ 0]org.apache.felix.framework (0.0.0)

See which bundles are running with:

$ bin/bundles 
ACTIV   [ 0]org.apache.felix.framework (0.0.0)  Bundle
ACTIV   [ 1]org.apache.felix.webconsole (3.1.8)     /tmp/kt/bundle/org.apache.felix.webconsole-3.1.8.jar
ACTIV   [ 2]org.apache.felix.webconsole.plugins.memoryusage (1.0.2)     /tmp/kt/bundle/org.apache.felix.webconsole.plugins.memoryusage-1.0.2.jar
INSTL   [ 3]org.apache.felix.deploymentadmin (0.9.0)    /tmp/kt/bundle/org.apache.felix.deploymentadmin-0.9.0.jar
ACTIV   [ 4]org.apache.felix.metatype (1.0.4)   /tmp/kt/bundle/org.apache.felix.metatype-1.0.4.jar

Shut the framework down with:

$ bin/shutdown-knapsack 
INFO: Bundle org.apache.felix.framework [0] OSGi framework is shutting down due to user request via shell.
...

Show the OSGi available services and binding relationships:

$ bin/services -d
[23]    javax.servlet.http.HttpServlet  [ 6]org.apache.felix.http.bundle (2.2.0)
[17]    org.osgi.service.cm.ManagedService  [ 1]org.apache.felix.webconsole (3.1.8)
    Used by [ 0]org.apache.felix.framework (0.0.0)
[16]    org.apache.felix.webconsole.ConfigurationPrinter    [ 1]org.apache.felix.webconsole (3.1.8)

Get help on available commands and parameters:

$ bin/help 
bundles [-b (brief)]    Get list of OSGi bundles installed in the framework.
printconfig             Print the Java system configuration.
help                    Print table of currently available commands.
shutdown-knapsack -f (force)    Stop all bundles and shutdown OSGi runtime.
services [-b (brief)] [-d (show dependencies)] [-p (show properties)]   Display OSGi services active in the framework.
log [-b (brief)]        Print OSGi log.
headers [bundle id]     Print bundle headers.
update                  Rescan the bundle directory or directories and update bundlespace accordingly.

License

Like Felix itself, knapsack is Apache 2.0 licensed.

Something went wrong with that request. Please try again.