org.eclipse.osgi.framework.adaptor
Interface FrameworkAdaptor

All Known Implementing Classes:
BaseAdaptor

public interface FrameworkAdaptor

FrameworkAdaptor interface to the osgi framework. This class is used to provide platform specific support for the osgi framework.

The OSGi framework will call this class to perform platform specific functions. Classes that implement FrameworkAdaptor MUST provide a constructor that takes as a parameter an array of Strings. This array will contain arguments to be handled by the FrameworkAdaptor. The FrameworkAdaptor implementation may define the format and content of its arguments. The constructor should parse the arguments passed to it and remember them. The initialize method should perform the actual processing of the adaptor arguments.

Clients may implement this interface.

Since:
3.1

Field Summary
static java.lang.String FRAMEWORK_SYMBOLICNAME
           
 
Method Summary
 void compactStorage()
          Compact/cleanup the persistent storage for the adaptor.
 BundleData createSystemBundleData()
          Creates a BundleData object for the System Bundle.
 void frameworkStart(BundleContext context)
          The framework will call this method after the System BundleActivator.start(BundleContext) has been called.
 void frameworkStop(BundleContext context)
          The framework will call this method before the System BundleActivator.stop(BundleContext) has been called.
 void frameworkStopping(BundleContext context)
          The framework will call this method before the process of framework shutdown is started.
 java.lang.ClassLoader getBundleClassLoaderParent()
          Returns the parent ClassLoader all BundleClassLoaders created.
 BundleWatcher getBundleWatcher()
          Returns the bundle watcher for this FrameworkAdaptor.
 org.eclipse.osgi.framework.log.FrameworkLog getFrameworkLog()
          Returns the FrameworkLog for the FrameworkAdaptor.
 int getInitialBundleStartLevel()
          Returns the initial bundle start level as maintained by this adaptor
 BundleData[] getInstalledBundles()
          Return a list of the installed bundles.
 PermissionStorage getPermissionStorage()
          Returns the PermissionStorage object which will be used to to manage the permission data.
 PlatformAdmin getPlatformAdmin()
          Returns the PlatformAdmin for this FrameworkAdaptor.
 java.util.Properties getProperties()
          Return the properties object for the adaptor.
 ServiceRegistry getServiceRegistry()
          Returns the ServiceRegistry object which will be used to manage ServiceReference bindings.
 State getState()
          Returns the State for this FrameworkAdaptor.
 long getTotalFreeSpace()
          Returns the total amount of free space available for bundle storage on the device.
 void handleRuntimeError(java.lang.Throwable error)
          Handles a RuntimeException or Error that was caught by the Framework and there is not a suitable caller to propagate the Throwable to.
 void initialize(EventPublisher eventPublisher)
          Initialize the FrameworkAdaptor object so that it is ready to be called by the framework.
 void initializeStorage()
          Initialize the persistent storage for the adaptor.
 BundleOperation installBundle(java.lang.String location, java.net.URLConnection source)
          Prepare to install a bundle from a URLConnection.
 java.net.URLConnection mapLocationToURLConnection(java.lang.String location)
          Map a location to a URLConnection.
 boolean matchDNChain(java.lang.String pattern, java.lang.String[] dnChain)
          Matches the distinguished name chain against a pattern of a distinguished name chain.
 void setInitialBundleStartLevel(int value)
          Sets the initial bundle start level
 BundleOperation uninstallBundle(BundleData bundledata)
          Prepare to uninstall a bundle.
 BundleOperation updateBundle(BundleData bundledata, java.net.URLConnection source)
          Prepare to update a bundle from a URLConnection.
 

Field Detail

FRAMEWORK_SYMBOLICNAME

static final java.lang.String FRAMEWORK_SYMBOLICNAME
See Also:
Constant Field Values
Method Detail

initialize

void initialize(EventPublisher eventPublisher)
Initialize the FrameworkAdaptor object so that it is ready to be called by the framework. Handle the arguments that were passed to the constructor. This method must be called before any other FrameworkAdaptor methods.

Parameters:
eventPublisher - The EventPublisher used to publish any events to the framework.

initializeStorage

void initializeStorage()
                       throws java.io.IOException
Initialize the persistent storage for the adaptor.

Throws:
java.io.IOException - If the adaptor is unable to initialize the bundle storage.

compactStorage

void compactStorage()
                    throws java.io.IOException
Compact/cleanup the persistent storage for the adaptor.

Throws:
java.io.IOException - If the adaptor is unable to compact the bundle storage.

getProperties

java.util.Properties getProperties()
Return the properties object for the adaptor. The properties in the returned object supplement the System properties. The framework may modify this object. The Framework will use the returned properties to set the System properties.

Returns:
The properties object for the adaptor.

getInstalledBundles

BundleData[] getInstalledBundles()
Return a list of the installed bundles. Each element in the list must be of type BundleData. Each BundleData corresponds to one bundle that is persistently stored. This method must construct BundleData objects for all installed bundles and return an array containing the objects. The returned array becomes the property of the framework.

Returns:
Array of installed BundleData objects, or null if none can be found.

mapLocationToURLConnection

java.net.URLConnection mapLocationToURLConnection(java.lang.String location)
                                                  throws BundleException
Map a location to a URLConnection. This is used by the Framework when installing a bundle from a spacified location.

Parameters:
location - of the bundle.
Returns:
URLConnection that represents the location.
Throws:
BundleException - if the mapping fails.

installBundle

BundleOperation installBundle(java.lang.String location,
                              java.net.URLConnection source)
Prepare to install a bundle from a URLConnection.

To complete the install, begin and then commit must be called on the returned BundleOperation object. If either of these methods throw a BundleException or some other error occurs, then undo must be called on the BundleOperation object to undo the change to persistent storage.

Parameters:
location - Bundle location.
source - URLConnection from which the bundle may be read. Any InputStreams returned from the source (URLConnections.getInputStream) must be closed by the BundleOperation object.
Returns:
BundleOperation object to be used to complete the install.

updateBundle

BundleOperation updateBundle(BundleData bundledata,
                             java.net.URLConnection source)
Prepare to update a bundle from a URLConnection.

To complete the update begin and then commit must be called on the returned BundleOperation object. If either of these methods throw a BundleException or some other error occurs, then undo must be called on the BundleOperation object to undo the change to persistent storage.

Parameters:
bundledata - BundleData to update.
source - URLConnection from which the updated bundle may be read. Any InputStreams returned from the source (URLConnections.getInputStream) must be closed by the BundleOperation object.
Returns:
BundleOperation object to be used to complete the update.

uninstallBundle

BundleOperation uninstallBundle(BundleData bundledata)
Prepare to uninstall a bundle.

To complete the uninstall, begin and then commit must be called on the returned BundleOperation object. If either of these methods throw a BundleException or some other error occurs, then undo must be called on the BundleOperation object to undo the change to persistent storage.

Parameters:
bundledata - BundleData to uninstall.
Returns:
BundleOperation object to be used to complete the uninstall.

getTotalFreeSpace

long getTotalFreeSpace()
                       throws java.io.IOException
Returns the total amount of free space available for bundle storage on the device.

Returns:
Free space available in bytes or -1 if it does not apply to this adaptor
Throws:
java.io.IOException - if an I/O error occurs determining the available space

getPermissionStorage

PermissionStorage getPermissionStorage()
                                       throws java.io.IOException
Returns the PermissionStorage object which will be used to to manage the permission data.

Returns:
The PermissionStorage object for the adaptor.
Throws:
java.io.IOException
See Also:
"org.osgi.service.permissionadmin.PermissionAdmin"

getServiceRegistry

ServiceRegistry getServiceRegistry()
Returns the ServiceRegistry object which will be used to manage ServiceReference bindings.

Returns:
The ServiceRegistry object for the adaptor.

frameworkStart

void frameworkStart(BundleContext context)
                    throws BundleException
The framework will call this method after the System BundleActivator.start(BundleContext) has been called. The context is the System Bundle's BundleContext. This method allows FrameworkAdaptors to have access to the OSGi framework to get services, register services and perform other OSGi operations.

Parameters:
context - The System Bundle's BundleContext.
Throws:
BundleException - on any error that may occur.

frameworkStop

void frameworkStop(BundleContext context)
                   throws BundleException
The framework will call this method before the System BundleActivator.stop(BundleContext) has been called. The context is the System Bundle's BundleContext. This method allows FrameworkAdaptors to have access to the OSGi framework to get services, register services and perform other OSGi operations.

Parameters:
context - The System Bundle's BundleContext.
Throws:
BundleException - on any error that may occur.

frameworkStopping

void frameworkStopping(BundleContext context)
The framework will call this method before the process of framework shutdown is started. This gives FrameworkAdaptors a chance to perform actions before the framework start level is decremented and all the bundles are stopped. This method will get called before the frameworkStop(BundleContext) method.

Parameters:
context - The System Bundle's BundleContext.

getInitialBundleStartLevel

int getInitialBundleStartLevel()
Returns the initial bundle start level as maintained by this adaptor

Returns:
the initial bundle start level

setInitialBundleStartLevel

void setInitialBundleStartLevel(int value)
Sets the initial bundle start level

Parameters:
value - the initial bundle start level

getFrameworkLog

org.eclipse.osgi.framework.log.FrameworkLog getFrameworkLog()
Returns the FrameworkLog for the FrameworkAdaptor. The FrameworkLog is used by the Framework and FrameworkAdaptor to log any error messages and FramworkEvents of type ERROR.

Returns:
The FrameworkLog to be used by the Framework.

createSystemBundleData

BundleData createSystemBundleData()
                                  throws BundleException
Creates a BundleData object for the System Bundle. The BundleData returned will be used to define the System Bundle for the Framework.

Returns:
the BundleData for the System Bundle.
Throws:
BundleException - if any error occurs while creating the System BundleData.

getBundleWatcher

BundleWatcher getBundleWatcher()
Returns the bundle watcher for this FrameworkAdaptor.

Returns:
the bundle watcher for this FrameworkAdaptor.

getPlatformAdmin

PlatformAdmin getPlatformAdmin()
Returns the PlatformAdmin for this FrameworkAdaptor.

This method will not be called until after frameworkStart(BundleContext) is called.

Returns:
the PlatformAdmin for this FrameworkAdaptor.

getState

State getState()
Returns the State for this FrameworkAdaptor.

This method will not be called until after frameworkStart(BundleContext) is called. The State returned is used by the framework to resolve bundle dependencies.

Returns:
the State for this FrameworkAdaptor.

getBundleClassLoaderParent

java.lang.ClassLoader getBundleClassLoaderParent()
Returns the parent ClassLoader all BundleClassLoaders created. All BundleClassLoaders that are created must use the ClassLoader returned by this method as a parent ClassLoader. Each call to this method must return the same ClassLoader object.

Returns:
the parent ClassLoader for all BundleClassLoaders created.

handleRuntimeError

void handleRuntimeError(java.lang.Throwable error)
Handles a RuntimeException or Error that was caught by the Framework and there is not a suitable caller to propagate the Throwable to. This gives the FrameworkAdaptor the ablity to handle such cases. For example, a FrameworkAdaptor may decide that such unexpected errors should cause an error message to be logged, or that the Framework should be terminated immediately.

Parameters:
error - The Throwable for the runtime error that is to be handled.

matchDNChain

boolean matchDNChain(java.lang.String pattern,
                     java.lang.String[] dnChain)
Matches the distinguished name chain against a pattern of a distinguished name chain.

Parameters:
pattern - the pattern of distinguished name (DN) chains to match against the dnChain. Wildcards "*" can be used in three cases:
  1. As a DN. In this case, the DN will consist of just the "*". It will match zero or more DNs. For example, "cn=me,c=US;*;cn=you" will match "cn=me,c=US";cn=you" and "cn=me,c=US;cn=her,c=CA;cn=you".
  2. As a DN prefix. In this case, the DN must start with "*,". The wild card will match zero or more RDNs at the start of a DN. For example, "*,cn=me,c=US;cn=you" will match "cn=me,c=US";cn=you" and "ou=my org unit,o=my org,cn=me,c=US;cn=you"
  3. As a value. In this case the value of a name value pair in an RDN will be a "*". The wildcard will match any value for the given name. For example, "cn=*,c=US;cn=you" will match "cn=me,c=US";cn=you" and "cn=her,c=US;cn=you", but it will not match "ou=my org unit,c=US;cn=you". If the wildcard does not occur by itself in the value, it will not be used as a wildcard. In other words, "cn=m*,c=US;cn=you" represents the common name of "m*" not any common name starting with "m".
dnChain - a distinguished name (DN) chain
Returns:
true if a dnChain matches the pattern. A value of false is returned if bundle signing is not supported.
Throws:
java.lang.IllegalArgumentException