org.apache.felix.framework
Class Felix

java.lang.Object
  org.apache.felix.framework.Felix

All Implemented Interfaces:

org.osgi.framework.Bundle, org.osgi.framework.launch.Framework

public class Felix
extends Object
implements org.osgi.framework.launch.Framework

Nested Class Summary

class

Felix.FelixResolver

Field Summary

Fields inherited from interface org.osgi.framework.Bundle

ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED

Constructor Summary

Felix(Map configMap)
This constructor creates a framework instance with a specified Map of configuration properties.

Method Summary

Enumeration	findEntries(String path, String filePattern, boolean recurse)
org.osgi.framework.BundleContext	getBundleContext()
long	getBundleId()
URL	getEntry(String name)
Enumeration	getEntryPaths(String path)
Dictionary	getHeaders()
Dictionary	getHeaders(String locale)
long	getLastModified()
String	getLocation()
int	getPersistentState()
org.osgi.framework.ServiceReference[]	getRegisteredServices() Returns an array of service references corresponding to the bundle's registered services.
URL	getResource(String name) Returns a URL to a named resource in the bundle.
Enumeration	getResources(String name)
org.osgi.framework.ServiceReference[]	getServicesInUse()
Map	getSignerCertificates(int signersType)
int	getState()
String	getSymbolicName()
org.osgi.framework.Version	getVersion()
boolean	hasPermission(Object obj)
void	init() This method initializes the framework, which is comprised of resolving the system bundle, reloading any cached bundles, and activating the system bundle.
Class	loadClass(String name)
void	setPersistentStateActive()
void	setPersistentStateInactive()
void	setPersistentStateUninstalled()
void	start() This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default).
void	start(int options)
void	stop() This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.
void	stop(int options)
String	toString()
void	uninstall()
void	update()
void	update(InputStream is)
org.osgi.framework.FrameworkEvent	waitForStop(long timeout) This method will cause the calling thread to block until the framework shuts down.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.osgi.framework.launch.Framework

getLocation, getSymbolicName

Methods inherited from interface org.osgi.framework.Bundle

findEntries, getBundleContext, getEntry, getEntryPaths, getHeaders, getHeaders, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, loadClass

Constructor Detail

Felix

public Felix(Map configMap)

This constructor creates a framework instance with a specified Map of configuration properties. Configuration properties are used internally by the framework to alter its default behavior. The configuration properties should have a String key and an Object value. The passed in Map is copied by the framework and all keys are converted to Strings.

Configuration properties are generally the sole means to configure the framework's default behavior; the framework does not typically refer to any system properties for configuration information. If a Map is supplied to this method for configuration properties, then the framework will consult the Map instance for any and all configuration properties. It is possible to specify a null for the configuration property map, in which case the framework will use its default behavior in all cases.

The following configuration properties can be specified (properties starting with "felix" are specific to Felix, while those starting with "org.osgi" are standard OSGi properties):

• org.osgi.framework.storage - Sets the directory to use as the bundle cache; by default bundle cache directory is felix-cache in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
• org.osgi.framework.storage.clean - Determines whether the bundle cache is flushed. The value can either be "none" or "onFirstInit", where "none" does not flush the bundle cache and "onFirstInit" flushes the bundle cache when the framework instance is first initialized. The default value is "none".
• felix.cache.rootdir - Sets the root directory to use to calculate the bundle cache directory for relative directory names. If org.osgi.framework.storage is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
• felix.cache.bufsize - Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
• org.osgi.framework.system.packages - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader. The framework will set this to a reasonable default. If the value is specified, it replaces any default value.
• org.osgi.framework.system.packages.extra - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader in addition to the packages in org.osgi.framework.system.packages. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in org.osgi.framework.system.packages.
• org.osgi.framework.bootdelegation - Specifies a comma-delimited list of packages that should be made implicitly available to all bundles from the parent class loader. It is recommended not to use this property since it breaks modularity. The default value is empty.
• felix.systembundle.activators - A List of BundleActivator instances that are started/stopped when the System Bundle is started/stopped. The specified instances will receive the System Bundle's BundleContext when invoked.
• felix.log.logger - An instance of Logger that the framework uses as its default logger.
• felix.log.level - An integer value indicating the degree of logging reported by the framework; the higher the value the more logging is reported. If zero ('0') is specified, then logging is turned off completely. The log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug). The default value is 1.
• org.osgi.framework.startlevel.beginning - The initial start level of the framework once it starts execution; the default value is 1.
• felix.startlevel.bundle - The default start level for newly installed bundles; the default value is 1.
• felix.service.urlhandlers - Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is "true". Activating the URL Handlers service will result in the URL.setURLStreamHandlerFactory() and URLConnection.setContentHandlerFactory() being called.
• felix.fragment.validation - Determines if installing unsupported fragment bundles throws an exception or logs a warning. Possible values are "exception" or "warning". The default value is "exception".

The Main class implements some functionality for default property file handling, which makes it possible to specify configuration properties and framework properties in files that are automatically loaded when starting the framework. If you plan to create your own framework instance, you may be able to take advantage of the features it provides; refer to its class documentation for more information.

The framework is not actually started until the start() method is called.

Parameters:

configMap - A map for obtaining configuration properties, may be null.

Method Detail

getBundleId

public long getBundleId()

Specified by:

getBundleId in interface org.osgi.framework.Bundle

Specified by:

getBundleId in interface org.osgi.framework.launch.Framework

getLastModified

public long getLastModified()

Specified by:

getLastModified in interface org.osgi.framework.Bundle

getPersistentState

public int getPersistentState()

setPersistentStateInactive

public void setPersistentStateInactive()

setPersistentStateActive

public void setPersistentStateActive()

setPersistentStateUninstalled

public void setPersistentStateUninstalled()

hasPermission

public boolean hasPermission(Object obj)

Specified by:

hasPermission in interface org.osgi.framework.Bundle

init

public void init()
          throws org.osgi.framework.BundleException

This method initializes the framework, which is comprised of resolving the system bundle, reloading any cached bundles, and activating the system bundle. The framework is left in the Bundle.STARTING state and reloaded bundles are in the Bundle.INSTALLED state. After successfully invoking this method, getBundleContext() will return a valid BundleContext for the system bundle. To finish starting the framework, invoke the start() method.

Specified by:

init in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException - if any error occurs.

start

public void start()
           throws org.osgi.framework.BundleException

This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default). If the init() was not explicitly invoked before calling this method, then it will be implicitly invoked before starting the framework.

Specified by:

start in interface org.osgi.framework.Bundle

Specified by:

start in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException - if any error occurs.

start

public void start(int options)
           throws org.osgi.framework.BundleException

Specified by:

start in interface org.osgi.framework.Bundle

Specified by:

start in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

stop

public void stop()
          throws org.osgi.framework.BundleException

This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.

Specified by:

stop in interface org.osgi.framework.Bundle

Specified by:

stop in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

stop

public void stop(int options)
          throws org.osgi.framework.BundleException

Specified by:

stop in interface org.osgi.framework.Bundle

Specified by:

stop in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

waitForStop

public org.osgi.framework.FrameworkEvent waitForStop(long timeout)
                                              throws InterruptedException

This method will cause the calling thread to block until the framework shuts down.

Specified by:

waitForStop in interface org.osgi.framework.launch.Framework

Parameters:

timeout - A timeout value.

Throws:

InterruptedException - If the thread was interrupted.

uninstall

public void uninstall()
               throws org.osgi.framework.BundleException

Specified by:

uninstall in interface org.osgi.framework.Bundle

Specified by:

uninstall in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

update

public void update()
            throws org.osgi.framework.BundleException

Specified by:

update in interface org.osgi.framework.Bundle

Specified by:

update in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

update

public void update(InputStream is)
            throws org.osgi.framework.BundleException

Specified by:

update in interface org.osgi.framework.Bundle

Specified by:

update in interface org.osgi.framework.launch.Framework

Throws:

org.osgi.framework.BundleException

toString

public String toString()

getBundleContext

public org.osgi.framework.BundleContext getBundleContext()

Specified by:

getBundleContext in interface org.osgi.framework.Bundle

getEntry

public URL getEntry(String name)

Specified by:

getEntry in interface org.osgi.framework.Bundle

getEntryPaths

public Enumeration getEntryPaths(String path)

Specified by:

getEntryPaths in interface org.osgi.framework.Bundle

findEntries

public Enumeration findEntries(String path,
                               String filePattern,
                               boolean recurse)

Specified by:

findEntries in interface org.osgi.framework.Bundle

getHeaders

public Dictionary getHeaders()

Specified by:

getHeaders in interface org.osgi.framework.Bundle

getHeaders

public Dictionary getHeaders(String locale)

Specified by:

getHeaders in interface org.osgi.framework.Bundle

getLocation

public String getLocation()

Specified by:

getLocation in interface org.osgi.framework.Bundle

getResource

public URL getResource(String name)

Returns a URL to a named resource in the bundle.

Specified by:

getResource in interface org.osgi.framework.Bundle

Returns:

a URL to named resource, or null if not found.

getResources

public Enumeration getResources(String name)
                         throws IOException

Specified by:

getResources in interface org.osgi.framework.Bundle

Throws:

IOException

getRegisteredServices

public org.osgi.framework.ServiceReference[] getRegisteredServices()

Returns an array of service references corresponding to the bundle's registered services.

Specified by:

getRegisteredServices in interface org.osgi.framework.Bundle

Returns:

an array of service references or null.

getServicesInUse

public org.osgi.framework.ServiceReference[] getServicesInUse()

Specified by:

getServicesInUse in interface org.osgi.framework.Bundle

getState

public int getState()

Specified by:

getState in interface org.osgi.framework.Bundle

getSymbolicName

public String getSymbolicName()

Specified by:

getSymbolicName in interface org.osgi.framework.Bundle

getVersion

public org.osgi.framework.Version getVersion()

Specified by:

getVersion in interface org.osgi.framework.Bundle

getSignerCertificates

public Map getSignerCertificates(int signersType)

Specified by:

getSignerCertificates in interface org.osgi.framework.Bundle

loadClass

public Class loadClass(String name)
                throws ClassNotFoundException

Specified by:

loadClass in interface org.osgi.framework.Bundle

Throws:

ClassNotFoundException