org.eclipse.osgi.framework.internal.core
Class Framework

java.lang.Object
  extended by org.eclipse.osgi.framework.internal.core.Framework
All Implemented Interfaces:
EventPublisher, EventDispatcher

public class Framework
extends java.lang.Object
implements EventDispatcher, EventPublisher

Core OSGi Framework class.


Field Summary
protected  boolean active
          Has the service space been started
protected  FrameworkAdaptor adaptor
          FrameworkAdaptor specific functions.
protected static AliasMapper aliasMapper
          The AliasMapper used to alias OS Names.
protected static int BATCHEVENT_BEGIN
           
protected static int BATCHEVENT_END
           
protected  EventListeners bundleEvent
          List of BundleContexts for bundle's BundleListeners.
protected static int BUNDLEEVENT
           
protected  EventListeners bundleEventSync
          List of BundleContexts for bundle's SynchronousBundleListeners.
protected static int BUNDLEEVENTSYNC
           
protected  BundleRepository bundles
          The bundles installed in the framework
protected  ConditionalPermissionAdminImpl condPermAdmin
           
protected  EventManager eventManager
          EventManager for event delivery.
protected  EventListeners frameworkEvent
          List of BundleContexts for bundle's FrameworkListeners.
protected static int FRAMEWORKEVENT
           
protected  java.util.Hashtable installLock
           
protected  PackageAdminImpl packageAdmin
          Package Admin object.
protected  PermissionAdminImpl permissionAdmin
          Package Admin object.
protected  java.util.Properties properties
          Framework properties object.
protected  EventListeners serviceEvent
          List of BundleContexts for bundle's ServiceListeners.
protected static int SERVICEEVENT
           
protected  long serviceid
          next free service id.
protected  ServiceRegistry serviceRegistry
          The ServiceRegistry
protected  StartLevelManager startLevelManager
          Startlevel object.
protected  SystemBundle systemBundle
          System Bundle object
 
Constructor Summary
Framework(FrameworkAdaptor adaptor)
          Constructor for the Framework instance.
 
Method Summary
protected  void checkAdminPermission(Bundle bundle, java.lang.String action)
          Check for specific AdminPermission (RFC 73)
protected  void checkGetServicePermission(java.lang.String name)
          Check for permission to get a service.
protected  void checkGetServicePermission(java.lang.String[] names)
          Check for permission to get a service.
protected  void checkRegisterServicePermission(java.lang.String[] names)
          Check for permission to register a service.
 void close()
          This method is called to destory the framework instance.
 void dispatchEvent(java.lang.Object l, java.lang.Object lo, int action, java.lang.Object object)
          Top level event dispatcher for the framework.
protected  AbstractBundle[] getAllBundles()
          Retrieve a list of all installed bundles.
 AbstractBundle getBundle(long id)
          Retrieve the bundle that has the given unique identifier.
protected  AbstractBundle getBundleByLocation(java.lang.String location)
          Locate an installed bundle with a given identity.
protected  AbstractBundle[] getBundleBySymbolicName(java.lang.String symbolicName)
          Locate an installed bundle with a given symbolic name
 AbstractBundle getBundleBySymbolicName(java.lang.String symbolicName, Version version)
          Retrieve the bundle that has the given symbolic name and version.
protected  BundleRepository getBundles()
          Retrieve the BundleRepository of all installed bundles.
protected  java.io.File getDataFile(AbstractBundle bundle, java.lang.String filename)
          Creates a File object for a file in the persistent storage area provided for the bundle by the framework.
protected  long getNextServiceId()
          Method to return the next available service id.
 java.lang.String getProperty(java.lang.String key)
          Retrieve the value of the named environment property.
protected  java.lang.String getProperty(java.lang.String key, java.lang.String def)
          Retrieve the value of the named environment property.
protected  ServiceReference[] getServiceReferences(java.lang.String clazz, java.lang.String filterstring, BundleContextImpl context, boolean allservices)
          Returns a list of ServiceReference objects.
protected  void initialize(FrameworkAdaptor adaptor)
          Initialize the framework to an unlaunched state.
protected  void initializeProperties(java.util.Properties adaptorProperties)
          Initialize the System properties by copying properties from the adaptor properties object.
 AbstractBundle installBundle(java.lang.String location)
          Install a bundle from a location.
protected  AbstractBundle installBundle(java.lang.String location, java.io.InputStream in)
          Install a bundle from an InputStream.
protected  void installSecurityManager()
          This is necessary for running from a JXE, otherwise the SecurityManager is set much later than we would like!
protected  AbstractBundle installWorker(java.lang.String location, java.security.PrivilegedExceptionAction action)
          Worker method to install a bundle.
protected  AbstractBundle installWorkerPrivileged(java.lang.String location, java.net.URLConnection source, java.security.AccessControlContext callerContext)
          Worker method to install a bundle.
protected  boolean isActive()
          This method return the state of the framework.
 void launch()
          Start the framework.
 void publishBundleEvent(int type, Bundle bundle)
          Deliver a BundleEvent to SynchronousBundleListeners (synchronous). and BundleListeners (asynchronous).
 void publishBundleEventPrivileged(BundleEvent event)
           
 void publishFrameworkEvent(int type, Bundle bundle, java.lang.Throwable throwable)
          Deliver a FrameworkEvent.
 void publishFrameworkEventPrivileged(FrameworkEvent event)
           
 void publishServiceEvent(int type, ServiceReference reference)
          Deliver a ServiceEvent.
 void publishServiceEventPrivileged(ServiceEvent event)
           
protected  void resumeBundle(AbstractBundle bundle)
          Resume a bundle.
protected  java.lang.Object setProperty(java.lang.String key, java.lang.String value)
          Set a system property.
 void shutdown()
          Stop the framework.
protected  boolean suspendBundle(AbstractBundle bundle, boolean lock)
          Suspend a bundle.
protected  boolean verifyExecutionEnvironment(java.util.Dictionary manifest)
          Verifies that the framework supports one of the required Execution Environments
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

adaptor

protected FrameworkAdaptor adaptor
FrameworkAdaptor specific functions.


properties

protected java.util.Properties properties
Framework properties object. A reference to the System.getProperies() object. The properties from the adaptor will be merged into these properties.


active

protected boolean active
Has the service space been started


bundles

protected BundleRepository bundles
The bundles installed in the framework


packageAdmin

protected PackageAdminImpl packageAdmin
Package Admin object. This object manages the exported packages.


permissionAdmin

protected PermissionAdminImpl permissionAdmin
Package Admin object. This object manages the exported packages.


startLevelManager

protected StartLevelManager startLevelManager
Startlevel object. This object manages the framework and bundle startlevels


serviceRegistry

protected ServiceRegistry serviceRegistry
The ServiceRegistry


serviceid

protected long serviceid
next free service id.


bundleEvent

protected EventListeners bundleEvent
List of BundleContexts for bundle's BundleListeners.


BUNDLEEVENT

protected static final int BUNDLEEVENT
See Also:
Constant Field Values

bundleEventSync

protected EventListeners bundleEventSync
List of BundleContexts for bundle's SynchronousBundleListeners.


BUNDLEEVENTSYNC

protected static final int BUNDLEEVENTSYNC
See Also:
Constant Field Values

serviceEvent

protected EventListeners serviceEvent
List of BundleContexts for bundle's ServiceListeners.


SERVICEEVENT

protected static final int SERVICEEVENT
See Also:
Constant Field Values

frameworkEvent

protected EventListeners frameworkEvent
List of BundleContexts for bundle's FrameworkListeners.


FRAMEWORKEVENT

protected static final int FRAMEWORKEVENT
See Also:
Constant Field Values

BATCHEVENT_BEGIN

protected static final int BATCHEVENT_BEGIN
See Also:
Constant Field Values

BATCHEVENT_END

protected static final int BATCHEVENT_END
See Also:
Constant Field Values

eventManager

protected EventManager eventManager
EventManager for event delivery.


installLock

protected java.util.Hashtable installLock

systemBundle

protected SystemBundle systemBundle
System Bundle object


aliasMapper

protected static AliasMapper aliasMapper
The AliasMapper used to alias OS Names.


condPermAdmin

protected ConditionalPermissionAdminImpl condPermAdmin
Constructor Detail

Framework

public Framework(FrameworkAdaptor adaptor)
Constructor for the Framework instance. This method initializes the framework to an unlaunched state.

Method Detail

initialize

protected void initialize(FrameworkAdaptor adaptor)
Initialize the framework to an unlaunched state. This method is called by the Framework constructor.


initializeProperties

protected void initializeProperties(java.util.Properties adaptorProperties)
Initialize the System properties by copying properties from the adaptor properties object. This method is called by the initialize method.


isActive

protected boolean isActive()
This method return the state of the framework.


close

public void close()
This method is called to destory the framework instance.


launch

public void launch()
Start the framework. When the framework is started. The following actions occur: 1. Event handling is enabled. Events can now be delivered to listeners. 2. All bundles which are recorded as started are started as described in the Bundle.start() method. These bundles are the bundles that were started when the framework was last stopped. Reports any exceptions that occur during startup using FrameworkEvents. 3. A FrameworkEvent of type FrameworkEvent.STARTED is broadcast.


shutdown

public void shutdown()
Stop the framework. When the framework is stopped. The following actions occur: 1. Suspend all started bundles as described in the Bundle.stop method except that the bundle is recorded as started. These bundles will be restarted when the framework is next started. Reports any exceptions that occur during stopping using FrameworkEvents. 2. Event handling is disabled.


verifyExecutionEnvironment

protected boolean verifyExecutionEnvironment(java.util.Dictionary manifest)
                                      throws BundleException
Verifies that the framework supports one of the required Execution Environments

Parameters:
manifest - BundleManifest of the bundle to verify the Execution Enviroment for
Returns:
boolean true if the required Execution Enviroment is available.
Throws:
BundleException - if the framework does not support the required Execution Environment.

getProperty

public java.lang.String getProperty(java.lang.String key)
Retrieve the value of the named environment property. Values are provided for the following properties:
org.osgi.framework.version
The version of the framework.
org.osgi.framework.vendor
The vendor of this framework implementation.
org.osgi.framework.language
The language being used. See ISO 639 for possible values.
org.osgi.framework.os.name
The name of the operating system of the hosting computer.
org.osgi.framework.os.version
The version number of the operating system of the hosting computer.
org.osgi.framework.processor
The name of the processor of the hosting computer.

Note: These last four properties are used by the Bundle-NativeCode manifest header's matching algorithm for selecting native code.

Parameters:
key - The name of the requested property.
Returns:
The value of the requested property, or null if the property is undefined.

getProperty

protected java.lang.String getProperty(java.lang.String key,
                                       java.lang.String def)
Retrieve the value of the named environment property. Values are provided for the following properties:
org.osgi.framework.version
The version of the framework.
org.osgi.framework.vendor
The vendor of this framework implementation.
org.osgi.framework.language
The language being used. See ISO 639 for possible values.
org.osgi.framework.os.name
The name of the operating system of the hosting computer.
org.osgi.framework.os.version
The version number of the operating system of the hosting computer.
org.osgi.framework.processor
The name of the processor of the hosting computer.

Note: These last four properties are used by the Bundle-NativeCode manifest header's matching algorithm for selecting native code.

Parameters:
key - The name of the requested property.
def - A default value is the requested property is not present.
Returns:
The value of the requested property, or the default value if the property is undefined.

setProperty

protected java.lang.Object setProperty(java.lang.String key,
                                       java.lang.String value)
Set a system property.

Parameters:
key - The name of the property to set.
value - The value to set.
Returns:
The previous value of the property or null if the property was not previously set.

installBundle

public AbstractBundle installBundle(java.lang.String location)
                             throws BundleException
Install a bundle from a location. The bundle is obtained from the location parameter as interpreted by the framework in an implementation dependent way. Typically, location will most likely be a URL.

Parameters:
location - The location identifier of the bundle to install.
Returns:
The Bundle object of the installed bundle.
Throws:
BundleException

installBundle

protected AbstractBundle installBundle(java.lang.String location,
                                       java.io.InputStream in)
                                throws BundleException
Install a bundle from an InputStream.

This method performs all the steps listed in installBundle(java.lang.String), except the bundle's content will be read from the InputStream. The location identifier specified will be used as the identity of the bundle.

Parameters:
location - The location identifier of the bundle to install.
in - The InputStream from which the bundle will be read.
Returns:
The Bundle of the installed bundle.
Throws:
BundleException

installWorker

protected AbstractBundle installWorker(java.lang.String location,
                                       java.security.PrivilegedExceptionAction action)
                                throws BundleException
Worker method to install a bundle. It obtains the reservation for the location and calls the specified action.

Parameters:
location - The location identifier of the bundle to install.
action - A PrivilegedExceptionAction which calls the real worker.
Returns:
The AbstractBundleof the installed bundle.
Throws:
BundleException - If the action throws an error.

installWorkerPrivileged

protected AbstractBundle installWorkerPrivileged(java.lang.String location,
                                                 java.net.URLConnection source,
                                                 java.security.AccessControlContext callerContext)
                                          throws BundleException
Worker method to install a bundle. It calls the FrameworkAdaptor object to install the bundle in persistent storage.

Parameters:
location - The location identifier of the bundle to install.
source - The URLConnection from which the bundle will be read.
Returns:
The AbstractBundleof the installed bundle.
Throws:
BundleException - If the provided stream cannot be read.

getBundle

public AbstractBundle getBundle(long id)
Retrieve the bundle that has the given unique identifier.

Parameters:
id - The identifier of the bundle to retrieve.
Returns:
A AbstractBundleobject, or null if the identifier doesn't match any installed bundle.

getBundleBySymbolicName

public AbstractBundle getBundleBySymbolicName(java.lang.String symbolicName,
                                              Version version)
Retrieve the bundle that has the given symbolic name and version.

Parameters:
symbolicName - The symbolic name of the bundle to retrieve
version - The version of the bundle to retrieve
Returns:
A AbstractBundleobject, or null if the identifier doesn't match any installed bundle.

getBundles

protected BundleRepository getBundles()
Retrieve the BundleRepository of all installed bundles. The list is valid at the time of the call to getBundles, but the framework is a very dynamic environment and bundles can be installed or uninstalled at anytime.

Returns:
The BundleRepository.

getAllBundles

protected AbstractBundle[] getAllBundles()
Retrieve a list of all installed bundles. The list is valid at the time of the call to getBundleAlls, but the framework is a very dynamic environment and bundles can be installed or uninstalled at anytime.

Returns:
An Array of AbstractBundleobjects, one object per installed bundle.

resumeBundle

protected void resumeBundle(AbstractBundle bundle)
Resume a bundle.

Parameters:
bundle - Bundle to resume.

suspendBundle

protected boolean suspendBundle(AbstractBundle bundle,
                                boolean lock)
Suspend a bundle.

Parameters:
bundle - Bundle to suspend.
lock - true if state change lock should be held when returning from this method.
Returns:
true if bundle was active and is now suspended.

getBundleByLocation

protected AbstractBundle getBundleByLocation(java.lang.String location)
Locate an installed bundle with a given identity.

Parameters:
location - string for the bundle
Returns:
Bundle object for bundle with the specified location or null if no bundle is installed with the specified location.

getBundleBySymbolicName

protected AbstractBundle[] getBundleBySymbolicName(java.lang.String symbolicName)
Locate an installed bundle with a given symbolic name

Parameters:
symbolicName - The symbolic name for the bundle
Returns:
Bundle object for bundle with the specified Unique or null if no bundle is installed with the specified location.

getServiceReferences

protected ServiceReference[] getServiceReferences(java.lang.String clazz,
                                                  java.lang.String filterstring,
                                                  BundleContextImpl context,
                                                  boolean allservices)
                                           throws InvalidSyntaxException
Returns a list of ServiceReference objects. This method returns a list of ServiceReference objects for services which implement and were registered under the specified class and match the specified filter criteria.

The list is valid at the time of the call to this method, however as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

filter is used to select the registered service whose properties objects contain keys and values which satisfy the filter. See FilterImplfor a description of the filter string syntax.

If filter is null, all registered services are considered to match the filter.

If filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The following steps are required to select a service:

  1. If the Java Runtime Environment supports permissions, the caller is checked for the ServicePermission to get the service with the specified class. If the caller does not have the correct permission, null is returned.
  2. If the filter string is not null, the filter string is parsed and the set of registered services which satisfy the filter is produced. If the filter string is null, then all registered services are considered to satisfy the filter.
  3. If clazz is not null, the set is further reduced to those services which are an instanceof and were registered under the specified class. The complete list of classes of which a service is an instance and which were specified when the service was registered is available from the service's Constants.OBJECTCLASSproperty.
  4. An array of ServiceReference to the selected services is returned.

Parameters:
clazz - The class name with which the service was registered, or null for all services.
filterstring - The filter criteria.
Returns:
An array of ServiceReference objects, or null if no services are registered which satisfy the search.
Throws:
InvalidSyntaxException - If filter contains an invalid filter string which cannot be parsed.

getNextServiceId

protected long getNextServiceId()
Method to return the next available service id. This method should be called while holding the registrations lock.

Returns:
next service id.

getDataFile

protected java.io.File getDataFile(AbstractBundle bundle,
                                   java.lang.String filename)
Creates a File object for a file in the persistent storage area provided for the bundle by the framework. If the adaptor does not have file system support, this method will return null.

A File object for the base directory of the persistent storage area provided for the context bundle by the framework can be obtained by calling this method with the empty string ("") as the parameter.


checkAdminPermission

protected void checkAdminPermission(Bundle bundle,
                                    java.lang.String action)
Check for specific AdminPermission (RFC 73)


checkRegisterServicePermission

protected void checkRegisterServicePermission(java.lang.String[] names)
Check for permission to register a service. The caller must have permission for ALL names.


checkGetServicePermission

protected void checkGetServicePermission(java.lang.String[] names)
Check for permission to get a service. The caller must have permission for at least ONE name.


checkGetServicePermission

protected void checkGetServicePermission(java.lang.String name)
Check for permission to get a service.


installSecurityManager

protected void installSecurityManager()
This is necessary for running from a JXE, otherwise the SecurityManager is set much later than we would like!


publishFrameworkEvent

public void publishFrameworkEvent(int type,
                                  Bundle bundle,
                                  java.lang.Throwable throwable)
Deliver a FrameworkEvent.

Specified by:
publishFrameworkEvent in interface EventPublisher
Parameters:
type - FrameworkEvent type.
bundle - Affected bundle or null for system bundle.
throwable - Related exception or null.
See Also:
FrameworkEvent

publishFrameworkEventPrivileged

public void publishFrameworkEventPrivileged(FrameworkEvent event)

publishBundleEvent

public void publishBundleEvent(int type,
                               Bundle bundle)
Deliver a BundleEvent to SynchronousBundleListeners (synchronous). and BundleListeners (asynchronous).

Parameters:
type - BundleEvent type.
bundle - Affected bundle or null.

publishBundleEventPrivileged

public void publishBundleEventPrivileged(BundleEvent event)

publishServiceEvent

public void publishServiceEvent(int type,
                                ServiceReference reference)
Deliver a ServiceEvent.

Parameters:
type - ServiceEvent type.
reference - Affected service reference.

publishServiceEventPrivileged

public void publishServiceEventPrivileged(ServiceEvent event)

dispatchEvent

public void dispatchEvent(java.lang.Object l,
                          java.lang.Object lo,
                          int action,
                          java.lang.Object object)
Top level event dispatcher for the framework.

Specified by:
dispatchEvent in interface EventDispatcher
Parameters:
l - BundleContext for receiving bundle
lo - BundleContext for receiving bundle
action - Event class type
object - ListenerQueue to populate