org.apache.felix.framework
Class Felix

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

All Implemented Interfaces:

Bundle, Framework

public class Felix
extends Object
implements Framework

Nested Class Summary

class

Felix.FelixResolver

Field Summary

Fields inherited from interface org.osgi.framework.Bundle

ACTIVE, INSTALLED, RESOLVED, 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

protected void	_refreshPackages(org.apache.felix.framework.BundleImpl[] bundles)
protected void	_resolveBundle(org.apache.felix.framework.BundleImpl bundle)
protected void	acquireInstallLock(String location)
protected void	addBundleListener(Bundle bundle, BundleListener l)
protected void	addFrameworkListener(Bundle bundle, FrameworkListener l)
protected void	addServiceListener(Bundle bundle, ServiceListener l, String f) Implementation for BundleContext.addServiceListener().
Enumeration	findEntries(String path, String filePattern, boolean recurse)
protected Bundle	getBundle(Class clazz) This method returns the bundle associated with the specified class if the class was loaded from a bundle from this framework instance.
protected Bundle	getBundle(long id) Implementation for BundleContext.getBundle().
protected Bundle	getBundle(String location) Retrieves a bundle from its location.
BundleContext	getBundleContext()
long	getBundleId() Returns the System Bundle unique identifier.
protected Bundle[]	getBundles() Implementation for BundleContext.getBundles().
protected File	getDataFile(org.apache.felix.framework.BundleImpl bundle, String s)
URL	getEntry(String name)
Enumeration	getEntryPaths(String path)
protected ExportedPackage[]	getExportedPackages(Bundle b) Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.
protected ExportedPackage[]	getExportedPackages(String pkgName) Returns the exported packages associated with the specified package name.
Dictionary	getHeaders()
Dictionary	getHeaders(String locale)
protected Bundle[]	getImportingBundles(ExportedPackage ep)
long	getLastModified()
String	getLocation()
int	getPersistentState()
protected String	getProperty(String key) Implementation for BundleContext.getProperty().
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)
protected Object	getService(Bundle bundle, ServiceReference ref)
ServiceReference[]	getServicesInUse()
int	getState()
String	getSymbolicName()
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.
protected Bundle	installBundle(String location, InputStream is)
Class	loadClass(String name)
protected void	refreshPackages(Bundle[] targets)
protected ServiceRegistration	registerService(org.apache.felix.framework.BundleImpl bundle, String[] classNames, Object svcObj, Dictionary dict) Implementation for BundleContext.registerService().
protected void	releaseInstallLock(String location)
protected void	removeBundleListener(Bundle bundle, BundleListener l)
protected void	removeFrameworkListener(Bundle bundle, FrameworkListener l)
protected void	removeServiceListener(Bundle bundle, ServiceListener l) Implementation for BundleContext.removeServiceListener().
protected boolean	resolveBundles(Bundle[] targets)
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) Start this System Bundle.
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) Stop this System Bundle.
String	toString()
protected boolean	ungetService(Bundle bundle, ServiceReference ref)
void	uninstall() The System Bundle cannot be uninstalled.
void	update() Stop and restart this System Bundle.
void	update(InputStream is) Stop and restart this System Bundle.
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, getState, loadClass

Constructor Detail

Felix

public Felix(Map configMap)
      throws Exception

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 - 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.

Throws:

Exception

Method Detail

getBundleId

public long getBundleId()

Description copied from interface: Framework

Returns the System Bundle unique identifier. This System Bundle is assigned the unique identifier zero (0).

Specified by:

getBundleId in interface Bundle

Specified by:

getBundleId in interface Framework

Returns:

0.

See Also:

Bundle.getBundleId()

getLastModified

public long getLastModified()

Specified by:

getLastModified in interface 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 Bundle

init

public void init()
          throws 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 Framework

Throws:

BundleException - if any error occurs.

start

public void start()
           throws 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 Bundle

Specified by:

start in interface Framework

Throws:

BundleException - if any error occurs.

See Also:

"Start Level Service Specification"

start

public void start(int options)
           throws BundleException

Description copied from interface: Framework

Start this System Bundle.

Calling this method is the same as calling Framework.start(). There are no start options for the System Bundle.

Specified by:

start in interface Bundle

Specified by:

start in interface Framework

Parameters:

options - Ignored. There are no start options for the System Bundle.

Throws:

BundleException - If this System Bundle could not be started.

See Also:

Framework.start()

stop

public void stop()
          throws 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 Bundle

Specified by:

stop in interface Framework

Throws:

BundleException - If stopping this System Bundle could not be initiated.

See Also:

"Start Level Service Specification"

stop

public void stop(int options)
          throws BundleException

Description copied from interface: Framework

Stop this System Bundle.

Calling this method is the same as calling Framework.stop(). There are no stop options for the System Bundle.

Specified by:

stop in interface Bundle

Specified by:

stop in interface Framework

Parameters:

options - Ignored. There are no stop options for the System Bundle.

Throws:

BundleException - If stopping this System Bundle could not be initiated.

See Also:

Framework.stop()

waitForStop

public 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 Framework

Parameters:

timeout - A timeout value.

Returns:

A Framework Event indicating the reason this method returned. The following FrameworkEvent types may be returned by this method.

• STOPPED - This System Bundle has been stopped which has shutdown its framework instance.
• STOPPED_UPDATE - This System Bundle has been updated which has shutdown and will restart its framework instance.
• STOPPED_BOOTCLASSPATH_MODIFIED - This System Bundle has been stopped which has shutdown its framework instance and a bootclasspath extension bundle has been installed or updated. The VM must be restarted in order for the changed boot class path to take affect.
• ERROR - The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.
• INFO - This method has timed out and returned before this System Bundle has stopped.

Throws:

InterruptedException - If the thread was interrupted.

uninstall

public void uninstall()
               throws BundleException

Description copied from interface: Framework

The System Bundle cannot be uninstalled.

This method always throws a BundleException.

Specified by:

uninstall in interface Bundle

Specified by:

uninstall in interface Framework

Throws:

BundleException - This System Bundle cannot be uninstalled.

update

public void update()
            throws BundleException

Description copied from interface: Framework

Stop and restart this System Bundle.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

1. Perform the steps in the Framework.stop() method to stop this System Bundle.
2. Perform the steps in the Framework.start() method to start this System Bundle.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Throws:

BundleException - If stopping and restarting this System Bundle could not be initiated.

update

public void update(InputStream is)
            throws BundleException

Description copied from interface: Framework

Stop and restart this System Bundle.

Calling this method is the same as calling Framework.update() except that any provided InputStream is immediately closed.

Specified by:

update in interface Bundle

Specified by:

update in interface Framework

Parameters:

is - Any provided InputStream is immediately closed before returning from this method and otherwise ignored.

Throws:

BundleException - If stopping and restarting this System Bundle could not be initiated.

toString

public String toString()

_resolveBundle

protected void _resolveBundle(org.apache.felix.framework.BundleImpl bundle)
                       throws BundleException

Throws:

BundleException

getProperty

protected String getProperty(String key)

Implementation for BundleContext.getProperty(). Returns environment property associated with the framework.

Parameters:

key - The name of the property to retrieve.

Returns:

The value of the specified property or null.

installBundle

protected Bundle installBundle(String location,
                               InputStream is)
                        throws BundleException

Throws:

BundleException

getBundle

protected Bundle getBundle(String location)

Retrieves a bundle from its location.

Parameters:

location - The location of the bundle to retrieve.

Returns:

The bundle associated with the location or null if there is no bundle associated with the location.

getBundle

protected Bundle getBundle(long id)

Implementation for BundleContext.getBundle(). Retrieves a bundle from its identifier.

Parameters:

id - The identifier of the bundle to retrieve.

Returns:

The bundle associated with the identifier or null if there is no bundle associated with the identifier.

getBundles

protected Bundle[] getBundles()

Implementation for BundleContext.getBundles(). Retrieves all installed bundles.

Returns:

An array containing all installed bundles or null if there are no installed bundles.

addBundleListener

protected void addBundleListener(Bundle bundle,
                                 BundleListener l)

removeBundleListener

protected void removeBundleListener(Bundle bundle,
                                    BundleListener l)

addServiceListener

protected void addServiceListener(Bundle bundle,
                                  ServiceListener l,
                                  String f)
                           throws InvalidSyntaxException

Implementation for BundleContext.addServiceListener(). Adds service listener to the listener list so that is can listen for ServiceEvents.

Parameters:

bundle - The bundle that registered the listener.

l - The service listener to add to the listener list.

f - The filter for the listener; may be null.

Throws:

InvalidSyntaxException

removeServiceListener

protected void removeServiceListener(Bundle bundle,
                                     ServiceListener l)

Implementation for BundleContext.removeServiceListener(). Removes service listeners from the listener list.

Parameters:

bundle - The context bundle of the listener

l - The service listener to remove from the listener list.

addFrameworkListener

protected void addFrameworkListener(Bundle bundle,
                                    FrameworkListener l)

removeFrameworkListener

protected void removeFrameworkListener(Bundle bundle,
                                       FrameworkListener l)

registerService

protected ServiceRegistration registerService(org.apache.felix.framework.BundleImpl bundle,
                                              String[] classNames,
                                              Object svcObj,
                                              Dictionary dict)

Implementation for BundleContext.registerService(). Registers a service for the specified bundle bundle.

Parameters:

classNames - A string array containing the names of the classes under which the new service is available.

svcObj - The service object or ServiceFactory.

dict - A dictionary of properties that further describe the service or null.

Returns:

A ServiceRegistration object or null.

getService

protected Object getService(Bundle bundle,
                            ServiceReference ref)

ungetService

protected boolean ungetService(Bundle bundle,
                               ServiceReference ref)

getDataFile

protected File getDataFile(org.apache.felix.framework.BundleImpl bundle,
                           String s)

getBundle

protected Bundle getBundle(Class clazz)

This method returns the bundle associated with the specified class if the class was loaded from a bundle from this framework instance. If the class was not loaded from a bundle or was loaded by a bundle in another framework instance, then null is returned.

Parameters:

clazz - the class for which to find its associated bundle.

Returns:

the bundle associated with the specified class or null if the class was not loaded by a bundle or its associated bundle belongs to a different framework instance.

getExportedPackages

protected ExportedPackage[] getExportedPackages(String pkgName)

Returns the exported packages associated with the specified package name. This is used by the PackageAdmin service implementation.

Parameters:

pkgName - The name of the exported package to find.

Returns:

The exported package or null if no matching package was found.

getExportedPackages

protected ExportedPackage[] getExportedPackages(Bundle b)

Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.

Parameters:

b - The bundle whose exported packages are to be retrieved or null if the exported packages of all bundles are to be retrieved.

Returns:

An array of exported packages.

getImportingBundles

protected Bundle[] getImportingBundles(ExportedPackage ep)

resolveBundles

protected boolean resolveBundles(Bundle[] targets)

refreshPackages

protected void refreshPackages(Bundle[] targets)

_refreshPackages

protected void _refreshPackages(org.apache.felix.framework.BundleImpl[] bundles)

acquireInstallLock

protected void acquireInstallLock(String location)
                           throws BundleException

Throws:

BundleException

releaseInstallLock

protected void releaseInstallLock(String location)

getBundleContext

public BundleContext getBundleContext()

Specified by:

getBundleContext in interface Bundle

getEntry

public URL getEntry(String name)

Specified by:

getEntry in interface Bundle

getEntryPaths

public Enumeration getEntryPaths(String path)

Specified by:

getEntryPaths in interface Bundle

findEntries

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

Specified by:

findEntries in interface Bundle

getHeaders

public Dictionary getHeaders()

Specified by:

getHeaders in interface Bundle

getHeaders

public Dictionary getHeaders(String locale)

Specified by:

getHeaders in interface Bundle

getLocation

public String getLocation()

Specified by:

getLocation in interface Bundle

getResource

public URL getResource(String name)

Returns a URL to a named resource in the bundle.

Specified by:

getResource in interface 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 Bundle

Throws:

IOException

getRegisteredServices

public ServiceReference[] getRegisteredServices()

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

Specified by:

getRegisteredServices in interface Bundle

Returns:

an array of service references or null.

getServicesInUse

public ServiceReference[] getServicesInUse()

Specified by:

getServicesInUse in interface Bundle

getState

public int getState()

Specified by:

getState in interface Bundle

getSymbolicName

public String getSymbolicName()

Specified by:

getSymbolicName in interface Bundle

loadClass

public Class loadClass(String name)
                throws ClassNotFoundException

Specified by:

loadClass in interface Bundle

Throws:

ClassNotFoundException