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

Fields

Modifier and Type	Field and Description
static String	FRAMEWORK_SYMBOLICNAME

Method Summary

Methods

Modifier and Type	Method and Description
void	compactStorage() Compact/cleanup the persistent storage for the adaptor.
BundleData	createSystemBundleData() Creates a BundleData object for the System Bundle.
Enumeration<URL>	findEntries(List<BundleData> datas, String path, String filePattern, int options) Returns resources entries for the specified bundle datas.
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.
ClassLoader	getBundleClassLoaderParent() Returns the parent ClassLoader all BundleClassLoaders created.
BundleWatcher	getBundleWatcher() Returns the bundle watcher for this FrameworkAdaptor.
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.
Properties	getProperties() Return the properties object for the adaptor.
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(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(String location, URLConnection source) Prepare to install a bundle from a URLConnection.
URLConnection	mapLocationToURLConnection(String location) Map a location to a URLConnection.
void	setInitialBundleStartLevel(int value) Sets the initial bundle start level
BundleOperation	uninstallBundle(BundleData bundledata) Prepare to uninstall a bundle.
BundleOperation	updateBundle(BundleData bundledata, URLConnection source) Prepare to update a bundle from a URLConnection.

Field Detail

FRAMEWORK_SYMBOLICNAME

static final 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 IOException

Initialize the persistent storage for the adaptor.

Throws:

IOException - If the adaptor is unable to initialize the bundle storage.

compactStorage

void compactStorage()
                    throws IOException

Compact/cleanup the persistent storage for the adaptor.

Throws:

IOException - If the adaptor is unable to compact the bundle storage.

getProperties

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

URLConnection mapLocationToURLConnection(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(String location,
                            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,
                           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 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:

IOException - if an I/O error occurs determining the available space

getPermissionStorage

PermissionStorage getPermissionStorage()
                                       throws IOException

Returns the PermissionStorage object which will be used to to manage the permission data.

Returns:

The PermissionStorage object for the adaptor.

Throws:

IOException

See Also:

"org.osgi.service.permissionadmin.PermissionAdmin"

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

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

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

findEntries

Enumeration<URL> findEntries(List<BundleData> datas,
                           String path,
                           String filePattern,
                           int options)

Returns resources entries for the specified bundle datas.

Parameters:

datas - the list of bundle datas to search in

path - The path name in which to look.

filePattern - The file name pattern for selecting resource names in the specified path.

options - The options for listing resource names.

Returns:

a list of resource URLs. If no resources are found then the empty list is returned.

See Also:

BundleClassLoader.findEntries(String, String, int), Bundle.findEntries(String, String, boolean)