org.apache.felix.framework
Class Felix

java.lang.Object
  extended by 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):

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


Copyright © 2006-2011 Apache Software Foundation. All Rights Reserved.