DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
...
Launching
...
and
...
Embedding
...
Felix
...
| Anchor | ||||
|---|---|---|---|---|
|
Introduction
The Felix OSGi framework is intended to be easily launchable and embeddable. For example, Felix avoids the use of system properties for configuration, since these are globals that can cause interference if multiple framework instances are created in the same VM. Felix is also implemented to multiplex singleton facilities, like the URL stream handler factory. The goal is to make it possible to use Felix in as many scenarios as possible; however, this is still just a goal. In other words, this is a work in progress and if any issues arise, it would be greatly appreciated if they are brought to the attention of the Felix community. The remainder of this document is divided into two main sections, one focusing on how to launch Felix and one focusing on how to embed Felix into a host application.
| Anchor | ||||
|---|---|---|---|---|
|
Launching Felix
Launching Felix is fairly simple and involves only three steps:
- Defining some configuration properties.
- Creating an instance of
org.apache.felix.framework.Felix
...
- .
...
- Invoking
...
- the
...
org.apache.felix.framework.Felix.start()
...
- method
...
- with
...
- the
...
- configuration
...
- properties.
...
The
...
only
...
configuration
...
properties
...
that
...
are
...
actually
...
required
...
to
...
start
...
Felix
...
are
...
ones
...
that
...
tell
...
it
...
where/how
...
to
...
locate
...
the
...
bundle
...
cache
...
profile
...
directory
...
where
...
installed
...
bundles
...
will
...
be
...
cached.
...
Felix'
...
bundle
...
cache
...
implementation
...
allows
...
you
...
to
...
configure
...
the
...
location
...
where
...
bundles
...
are
...
cached
...
using
...
configuration
...
properties.
...
At
...
a
...
minimum,
...
either
...
a
...
bundle
...
cache
...
profile
...
name
...
or
...
directory
...
must
...
be
...
specified;
...
see
...
the
...
...
...
...
for
...
more
...
detailed
...
information
...
on
...
configuring
...
the
...
bundle
...
cache.
...
Besides
...
configuration
...
properties
...
for
...
the
...
bundle
...
cache,
...
it
...
is
...
usually
...
necessary
...
to
...
set
...
the
...
org.osgi.framework.system.packages
...
configuration
...
property
...
to
...
export
...
packages
...
from
...
the
...
class
...
path,
...
such
...
as
...
the
...
OSGi
...
interface
...
classes
...
(e.g.,
...
org.osgi.framework
...
)
...
on
...
which
...
all
...
bundles
...
depend.
...
If
...
you
...
are
...
creating
...
a
...
launcher
...
for
...
Felix,
...
then
...
the
...
felix.auto.start
...
configuration
...
property
...
may
...
also
...
be
...
used
...
to
...
automatically
...
install
...
and
...
start
...
various
...
bundles;
...
see
...
the
...
...
...
for
...
more
...
information
...
on
...
configuring
...
Felix
...
and
...
on
...
the
...
various
...
configuration
...
properties.
...
The
...
remainder
...
of
...
this
...
section
...
describes
...
how
...
the
...
standard
...
Felix
...
launcher
...
works
...
as
...
well
...
as
...
how
...
to
...
create
...
a
...
custom
...
launcher
...
for
...
Felix.
...
| Anchor | ||||
|---|---|---|---|---|
|
Standard Felix Launcher
Sufficiently detailed description of the standard Felix launcher to go here.
| Anchor | ||||
|---|---|---|---|---|
|
Custom Felix Launcher
This section creates a bare-bones launcher to demonstrate the minimum requirements for creating an interactive launcher for the Felix framework. This example uses the standard Felix shell bundles for interactivity, but any other bundles could be used instead. For example, the shell service and telnet bundles could be used to lauch Felix and make it remotely accessible.
This example launcher project has the following directory structure:
| No Format |
|---|
} h2. Standard Felix Launcher Sufficiently detailed description of the standard Felix launcher to go here. {anchor:custom-launcher} h2. Custom Felix Launcher This section creates a bare-bones launcher to demonstrate the minimum requirements for creating an interactive launcher for the Felix framework. This example uses the standard Felix shell bundles for interactivity, but any other bundles could be used instead. For example, the shell service and telnet bundles could be used to lauch Felix and make it remotely accessible. This example launcher project has the following directory structure: {noformat} launcher/ lib/ org.apache.felix.framework-0.8.0-SNAPSHOT.jar org.osgi.core-0.8.0-SNAPSHOT.jar bundle/ org.apache.felix.shell-0.8.0-SNAPSHOT.jar org.apache.felix.shell.tui-0.8.0-SNAPSHOT.jar src/ example/ Main.java {noformat} The {{ |
The lib/
...
directory
...
contains
...
the
...
JAR
...
files
...
for
...
the
...
framework
...
as
...
well
...
as
...
the
...
OSGi
...
interfaces.
...
The
...
bundle/
...
directory
...
contains
...
the
...
shell
...
service
...
and
...
textual
...
shell
...
interface
...
bundles
...
that
...
will
...
be
...
used
...
for
...
interacting
...
with
...
the
...
framework
...
instance.
...
Note:
...
If
...
you
...
do
...
not
...
launch
...
Felix
...
with
...
interactive
...
bundles,
...
it
...
will
...
appear
...
as
...
if
...
the
...
framework
...
instance
...
is
...
hung,
...
but
...
it
...
is
...
actually
...
just
...
sitting
...
there
...
waiting
...
for
...
someone
...
to
...
tell
...
it
...
to
...
do
...
something.
...
The
...
src/example/
...
directory
...
contains
...
the
...
following
...
Main.java
...
file,
...
which
...
is
...
a
...
very
...
simplistic
...
Felix
...
launcher.
| Code Block |
|---|
} package example; import java.util.Map; import org.osgi.framework.Constants; import org.apache.felix.framework.Felix; import org.apache.felix.framework.cache.BundleCache; import org.apache.felix.framework.util.MutablePropertyResolverImpl; import org.apache.felix.framework.util.StringMap; import org.apache.felix.framework.util.FelixConstants; public class Main { private static Felix m_felix = null; public static void main(String[] argv) throws Exception { // Print welcome banner. System.out.println("\nWelcome to Felix."); System.out.println("=================\n"); Map configMap = new StringMap(false); configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES, "org.osgi.framework; version=1.3.0," + "org.osgi.service.packageadmin; version=1.2.0," + "org.osgi.service.startlevel; version=1.0.0," + "org.osgi.service.url; version=1.0.0"); configMap.put(FelixConstants.AUTO_START_PROP + ".1", "file:bundle/org.apache.felix.shell-0.8.0-SNAPSHOT.jar " + "file:bundle/org.apache.felix.shell.tui-0.8.0-SNAPSHOT.jar"); configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, "cache"); try { // Now create an instance of the framework. m_felix = new Felix(); m_felix.start( new MutablePropertyResolverImpl(configMap), null); } catch (Exception ex) { System.err.println("Could not create framework: " + ex); ex.printStackTrace(); System.exit(-1); } } } {code} |
This
...
launcher
...
has
...
all
...
information
...
hard
...
coded
...
in
...
it,
...
unlike
...
the
...
default
...
Felix
...
launcher,
...
which
...
loads
...
configuration
...
properties
...
from
...
files
...
and
...
performs
...
variable
...
substitution.
...
This
...
simple
...
launcher
...
provides
...
a
...
good
...
starting
...
point
...
if
...
the
...
features
...
of
...
the
...
default
...
launcher
...
are
...
not
...
necessary.
...
For
...
example,
...
if
...
you
...
want
...
to
...
create
...
a
...
launcher
...
that
...
automatically
...
deletes
...
the
...
bundle
...
cache
...
directory
...
each
...
time
...
it
...
starts,
...
then
...
it
...
is
...
quite
...
easy
...
to
...
figure
...
out
...
how
...
to
...
do
...
that
...
with
...
this
...
simple
...
launcher.
...
By
...
breaking
...
down
...
the
...
above
...
source
...
code
...
into
...
small
...
chunks,
...
it
...
is
...
quite
...
easy
...
to
...
see
...
what
...
is
...
going
...
on.
| Code Block |
|---|
} Map configMap = new StringMap(false); {code} |
This
...
simply
...
creates
...
a
...
map
...
to
...
hold
...
configuration
...
properties
...
where
...
the
...
keys
...
are
...
strings
...
and
...
lookups
...
are
...
case
...
insensitive.
| Code Block |
|---|
} configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES, "org.osgi.framework; version=1.3.0," + "org.osgi.service.packageadmin; version=1.2.0," + "org.osgi.service.startlevel; version=1.0.0," + "org.osgi.service.url; version=1.0.0"); {code} |
This
...
sets
...
the
...
Constants.FRAMEWORK_SYSTEMPACKAGES
...
configuration
...
property
...
(string
...
value
...
"
...
org.osgi.framework.system.packages
...
"),
...
which
...
specifies
...
the
...
class
...
path
...
packages
...
the
...
system
...
bundle
...
should
...
export;
...
this
...
is
...
how
...
classes
...
on
...
the
...
class
...
path
...
are
...
made
...
available
...
to
...
bundles.
...
This
...
example
...
only
...
exports
...
the
...
core
...
OSGi
...
API
...
packages,
...
but
...
other
...
JRE
...
packages
...
could
...
also
...
be
...
added,
...
such
...
as
...
javax.swing
...
.
...
For
...
example,
...
the
...
default
...
Felix
...
launcher
...
defines
...
properties
...
for
...
all
...
packages
...
in
...
various
...
JRE
...
versions
...
(e.g.,
...
1.3.x,
...
1.4.x,
...
1.5.x)
...
and
...
appends
...
them
...
to
...
this
...
property
...
using
...
property
...
substitution.
| Code Block |
|---|
} configMap.put(FelixConstants.AUTO_START_PROP + ".1", "file:bundle/org.apache.felix.shell-0.8.0-SNAPSHOT.jar " + "file:bundle/org.apache.felix.shell.tui-0.8.0-SNAPSHOT.jar"); {code} |
This
...
sets
...
the
...
FelixConstants.AUTO_START_PROP
...
configuration
...
property
...
(string
...
value
...
"
...
felix.auto.start
...
"),
...
which
...
is
...
a
...
space-delimited
...
list
...
of
...
bundle
...
URLs
...
that
...
the
...
framework
...
will
...
automatically
...
install
...
and
...
start
...
when
...
the
...
framework
...
starts.
...
However,
...
this
...
property
...
key
...
cannot
...
be
...
used
...
as
...
is;
...
it
...
must
...
be
...
appended
...
with
...
a
...
"."
...
and
...
then
...
a
...
number,
...
where
...
the
...
number
...
represents
...
the
...
start
...
level
...
for
...
the
...
bundle
...
when
...
it
...
is
...
installed.
...
In
...
this
...
particular
...
example,
...
".1"
...
is
...
appended
...
to
...
the
...
property
...
name,
...
thus
...
the
...
two
...
bundles
...
will
...
be
...
installed
...
into
...
start
...
level
...
one.
...
This
...
example
...
uses
...
relative
...
file:
...
URLs,
...
which
...
will
...
load
...
the
...
bundles
...
from
...
the
...
bundle/
...
directory
...
assuming
...
that
...
the
...
launcher
...
is
...
started
...
from
...
the
...
root
...
directory
...
of
...
the
...
launcher
...
project.
...
It
...
is
...
also
...
possible
...
to
...
specify
...
absolute
...
URLs
...
or
...
remote
...
URLs.
| Code Block |
|---|
} configMap.put(BundleCache.CACHE_PROFILE_DIR_PROP, "cache"); {code} |
This
...
sets
...
the
...
last
...
configuration
...
property,
...
BundleCache.CACHE_PROFILE_DIR_PROP
...
(string
...
value
...
"
...
felix.cache.profiledir
...
"),
...
which
...
is
...
a
...
string
...
that
...
specifies
...
the
...
precise
...
directory
...
to
...
be
...
used
...
as
...
the
...
bundle
...
cache
...
profile
...
directory;
...
the
...
Felix
...
bundle
...
cache
...
supports
...
other
...
properties
...
to
...
configure
...
its
...
behavior,
...
but
...
those
...
are
...
not
...
covered
...
here.
...
In
...
this
...
example,
...
the
...
bundle
...
cache
...
profile
...
directory
...
is
...
specified
...
as
...
a
...
relative
...
directory
...
called
...
"
...
cache
...
".
...
Assuming
...
that
...
the
...
launcher
...
is
...
executed
...
from
...
the
...
root
...
directory
...
of
...
the
...
launcher
...
project,
...
then
...
the
...
bundle
...
cache
...
profile
...
directory
...
will
...
be
...
created
...
in
...
the
...
root
...
directory
...
of
...
the
...
project.
| Code Block |
|---|
} m_felix = new Felix(); m_felix.start( new MutablePropertyResolverImpl(configMap), null); {code} |
The
...
last
...
steps
...
create
...
the
...
framework
...
instance
...
and
...
start
...
it.
...
The
...
configuration
...
property
...
map
...
is
...
converted
...
to
...
an
...
instance
...
of
...
a
...
PropertyResolver
...
before
...
being
...
passed
...
into
...
the
...
Felix.start()
...
method.
...
The
...
following
...
command
...
compiles
...
the
...
launcher
...
when
...
run
...
from
...
the
...
root
...
directory
...
of
...
the
...
launcher
...
project:
| No Format |
|---|
} javac -d . -classpath lib/org.apache.felix.framework-0.8.0-SNAPSHOT.jar:lib/org.osgi.core-0.8.0-SNAPSHOT.jar src/example/Main.java {noformat} |
After
...
executing
...
this
...
command,
...
an
...
example/
...
directory
...
is
...
created
...
in
...
the
...
current
...
directory,
...
which
...
contains
...
the
...
generated
...
class
...
file.
...
The
...
following
...
command
...
executes
...
the
...
simple
...
launcher
...
when
...
run
...
from
...
the
...
root
...
directory
...
of
...
the
...
launcher
...
project:
| No Format |
|---|
} java -cp .:lib/org.apache.felix.framework-0.8.0-SNAPSHOT.jar:lib/org.osgi.core-0.8.0-SNAPSHOT.jar example.Main {noformat} |
After
...
executing
...
this
...
command,
...
a
...
cache/
...
directory
...
is
...
created
...
that
...
contains
...
the
...
installed
...
bundles,
...
which
...
were
...
installed
...
from
...
the
...
bundle/
...
directory.
...
| Anchor | ||||
|---|---|---|---|---|
|
Embedding Felix
to do
| Anchor | ||||
|---|---|---|---|---|
|
Host/Felix Interaction
to do
| Anchor | ||||
|---|---|---|---|---|
|
Providing Host Application Services
to do
| Anchor | ||||
|---|---|---|---|---|
|
Using Services Provided by Bundles
to do