org.apache.felix.framework
Class Felix

java.lang.Object
  extended by org.apache.felix.framework.Felix
All Implemented Interfaces:
org.osgi.framework.Bundle, Framework

public class Felix
extends java.lang.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(java.util.Map configMap)
           This constructor creates a framework instance with a specified Map of configuration properties.
 
Method Summary
protected  void acquireInstallLock(java.lang.String location)
           
protected  void addBundleListener(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleListener l)
           
protected  void addFrameworkListener(org.osgi.framework.Bundle bundle, org.osgi.framework.FrameworkListener l)
           
protected  void addServiceListener(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceListener l, java.lang.String f)
          Implementation for BundleContext.addServiceListener().
 java.util.Enumeration findEntries(java.lang.String path, java.lang.String filePattern, boolean recurse)
           
protected  org.osgi.framework.Bundle getBundle(java.lang.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  org.osgi.framework.Bundle getBundle(long id)
          Implementation for BundleContext.getBundle().
protected  org.osgi.framework.Bundle getBundle(java.lang.String location)
          Retrieves a bundle from its location.
 org.osgi.framework.BundleContext getBundleContext()
           
 long getBundleId()
          Returns the Framework unique identifier.
protected  org.osgi.framework.Bundle[] getBundles()
          Implementation for BundleContext.getBundles().
protected  java.io.File getDataFile(org.apache.felix.framework.BundleImpl bundle, java.lang.String s)
           
 java.net.URL getEntry(java.lang.String name)
           
 java.util.Enumeration getEntryPaths(java.lang.String path)
           
protected  org.osgi.service.packageadmin.ExportedPackage[] getExportedPackages(org.osgi.framework.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  org.osgi.service.packageadmin.ExportedPackage[] getExportedPackages(java.lang.String pkgName)
          Returns the exported packages associated with the specified package name.
 java.util.Dictionary getHeaders()
           
 java.util.Dictionary getHeaders(java.lang.String locale)
           
protected  org.osgi.framework.Bundle[] getImportingBundles(org.osgi.service.packageadmin.ExportedPackage ep)
           
 long getLastModified()
           
 java.lang.String getLocation()
           
 int getPersistentState()
           
protected  java.lang.String getProperty(java.lang.String key)
          Implementation for BundleContext.getProperty().
 org.osgi.framework.ServiceReference[] getRegisteredServices()
          Returns an array of service references corresponding to the bundle's registered services.
 java.net.URL getResource(java.lang.String name)
          Returns a URL to a named resource in the bundle.
 java.util.Enumeration getResources(java.lang.String name)
           
protected  java.lang.Object getService(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceReference ref)
           
 org.osgi.framework.ServiceReference[] getServicesInUse()
           
 int getState()
           
 java.lang.String getSymbolicName()
           
 boolean hasPermission(java.lang.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  org.osgi.framework.Bundle installBundle(java.lang.String location, java.io.InputStream is)
           
 java.lang.Class loadClass(java.lang.String name)
           
protected  org.osgi.framework.ServiceRegistration registerService(org.apache.felix.framework.BundleImpl bundle, java.lang.String[] classNames, java.lang.Object svcObj, java.util.Dictionary dict)
          Implementation for BundleContext.registerService().
protected  void releaseInstallLock(java.lang.String location)
           
protected  void removeBundleListener(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleListener l)
           
protected  void removeFrameworkListener(org.osgi.framework.Bundle bundle, org.osgi.framework.FrameworkListener l)
           
protected  void removeServiceListener(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceListener l)
          Implementation for BundleContext.removeServiceListener().
 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 Framework.
 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 Framework.
 java.lang.String toString()
           
protected  boolean ungetService(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceReference ref)
           
 void uninstall()
          The Framework cannot be uninstalled.
 void update()
          Stop and restart this Framework.
 void update(java.io.InputStream is)
          Stop and restart this 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, getState, loadClass
 

Constructor Detail

Felix

public Felix(java.util.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):

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()
Description copied from interface: Framework
Returns the Framework unique identifier. This Framework is assigned the unique identifier zero (0) since this Framework is also a System Bundle.

Specified by:
getBundleId in interface org.osgi.framework.Bundle
Specified by:
getBundleId in interface Framework
Returns:
0.
See Also:
Bundle.getBundleId()

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(java.lang.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 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 Framework
Throws:
org.osgi.framework.BundleException - if any error occurs.
See Also:
"Start Level Service Specification"

start

public void start(int options)
           throws org.osgi.framework.BundleException
Description copied from interface: Framework
Start this Framework.

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

Specified by:
start in interface org.osgi.framework.Bundle
Specified by:
start in interface Framework
Parameters:
options - Ignored. There are no start options for the Framework.
Throws:
org.osgi.framework.BundleException - If this Framework could not be started.
See Also:
Framework.start()

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 Framework
Throws:
org.osgi.framework.BundleException - If stopping this Framework could not be initiated.
See Also:
"Start Level Service Specification"

stop

public void stop(int options)
          throws org.osgi.framework.BundleException
Description copied from interface: Framework
Stop this Framework.

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

Specified by:
stop in interface org.osgi.framework.Bundle
Specified by:
stop in interface Framework
Parameters:
options - Ignored. There are no stop options for the Framework.
Throws:
org.osgi.framework.BundleException - If stopping this Framework could not be initiated.
See Also:
Framework.stop()

waitForStop

public FrameworkEvent waitForStop(long timeout)
                           throws java.lang.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 Framework has been stopped.
  • STOPPED_UPDATE - This Framework has been updated which has shutdown and will now restart.
  • STOPPED_BOOTCLASSPATH_MODIFIED - This Framework has been stopped 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 Framework has stopped.
Throws:
java.lang.InterruptedException - If the thread was interrupted.

uninstall

public void uninstall()
               throws org.osgi.framework.BundleException
Description copied from interface: Framework
The Framework cannot be uninstalled.

This method always throws a BundleException.

Specified by:
uninstall in interface org.osgi.framework.Bundle
Specified by:
uninstall in interface Framework
Throws:
org.osgi.framework.BundleException - This Framework cannot be uninstalled.

update

public void update()
            throws org.osgi.framework.BundleException
Description copied from interface: Framework
Stop and restart this Framework.

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 Framework.
  2. Perform the steps in the Framework.start() method to start this Framework.

Specified by:
update in interface org.osgi.framework.Bundle
Specified by:
update in interface Framework
Throws:
org.osgi.framework.BundleException - If stopping and restarting this Framework could not be initiated.

update

public void update(java.io.InputStream is)
            throws org.osgi.framework.BundleException
Description copied from interface: Framework
Stop and restart this Framework.

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

Specified by:
update in interface org.osgi.framework.Bundle
Specified by:
update in interface Framework
Parameters:
is - Any provided InputStream is immediately closed before returning from this method and otherwise ignored.
Throws:
org.osgi.framework.BundleException - If stopping and restarting this Framework could not be initiated.

toString

public java.lang.String toString()

getProperty

protected java.lang.String getProperty(java.lang.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 org.osgi.framework.Bundle installBundle(java.lang.String location,
                                                  java.io.InputStream is)
                                           throws org.osgi.framework.BundleException
Throws:
org.osgi.framework.BundleException

getBundle

protected org.osgi.framework.Bundle getBundle(java.lang.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 org.osgi.framework.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 org.osgi.framework.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(org.osgi.framework.Bundle bundle,
                                 org.osgi.framework.BundleListener l)

removeBundleListener

protected void removeBundleListener(org.osgi.framework.Bundle bundle,
                                    org.osgi.framework.BundleListener l)

addServiceListener

protected void addServiceListener(org.osgi.framework.Bundle bundle,
                                  org.osgi.framework.ServiceListener l,
                                  java.lang.String f)
                           throws org.osgi.framework.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:
org.osgi.framework.InvalidSyntaxException

removeServiceListener

protected void removeServiceListener(org.osgi.framework.Bundle bundle,
                                     org.osgi.framework.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(org.osgi.framework.Bundle bundle,
                                    org.osgi.framework.FrameworkListener l)

removeFrameworkListener

protected void removeFrameworkListener(org.osgi.framework.Bundle bundle,
                                       org.osgi.framework.FrameworkListener l)

registerService

protected org.osgi.framework.ServiceRegistration registerService(org.apache.felix.framework.BundleImpl bundle,
                                                                 java.lang.String[] classNames,
                                                                 java.lang.Object svcObj,
                                                                 java.util.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 java.lang.Object getService(org.osgi.framework.Bundle bundle,
                                      org.osgi.framework.ServiceReference ref)

ungetService

protected boolean ungetService(org.osgi.framework.Bundle bundle,
                               org.osgi.framework.ServiceReference ref)

getDataFile

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

getBundle

protected org.osgi.framework.Bundle getBundle(java.lang.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 org.osgi.service.packageadmin.ExportedPackage[] getExportedPackages(java.lang.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 org.osgi.service.packageadmin.ExportedPackage[] getExportedPackages(org.osgi.framework.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 org.osgi.framework.Bundle[] getImportingBundles(org.osgi.service.packageadmin.ExportedPackage ep)

acquireInstallLock

protected void acquireInstallLock(java.lang.String location)
                           throws org.osgi.framework.BundleException
Throws:
org.osgi.framework.BundleException

releaseInstallLock

protected void releaseInstallLock(java.lang.String location)

getBundleContext

public org.osgi.framework.BundleContext getBundleContext()
Specified by:
getBundleContext in interface org.osgi.framework.Bundle

getEntry

public java.net.URL getEntry(java.lang.String name)
Specified by:
getEntry in interface org.osgi.framework.Bundle

getEntryPaths

public java.util.Enumeration getEntryPaths(java.lang.String path)
Specified by:
getEntryPaths in interface org.osgi.framework.Bundle

findEntries

public java.util.Enumeration findEntries(java.lang.String path,
                                         java.lang.String filePattern,
                                         boolean recurse)
Specified by:
findEntries in interface org.osgi.framework.Bundle

getHeaders

public java.util.Dictionary getHeaders()
Specified by:
getHeaders in interface org.osgi.framework.Bundle

getHeaders

public java.util.Dictionary getHeaders(java.lang.String locale)
Specified by:
getHeaders in interface org.osgi.framework.Bundle

getLocation

public java.lang.String getLocation()
Specified by:
getLocation in interface org.osgi.framework.Bundle

getResource

public java.net.URL getResource(java.lang.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 java.util.Enumeration getResources(java.lang.String name)
                                   throws java.io.IOException
Specified by:
getResources in interface org.osgi.framework.Bundle
Throws:
java.io.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 java.lang.String getSymbolicName()
Specified by:
getSymbolicName in interface org.osgi.framework.Bundle

loadClass

public java.lang.Class loadClass(java.lang.String name)
                          throws java.lang.ClassNotFoundException
Specified by:
loadClass in interface org.osgi.framework.Bundle
Throws:
java.lang.ClassNotFoundException


Copyright © 2006-2009 The Apache Software Foundation. All Rights Reserved.