org.eclipse.osgi.baseadaptor
Class BaseAdaptor

java.lang.Object
  extended by org.eclipse.osgi.baseadaptor.BaseAdaptor
All Implemented Interfaces:
FrameworkAdaptor

public class BaseAdaptor
extends java.lang.Object
implements FrameworkAdaptor

A Framework adaptor implementation that allows additional functionality to be hooked in. Hooks are configured using HookConfigurator objects. A framework extension may add hook configurators which can be used to add hooks to the HookRegistry.

Since:
3.2
See Also:
HookConfigurator, HookRegistry, AdaptorHook

Field Summary
 
Fields inherited from interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor
FRAMEWORK_SYMBOLICNAME
 
Constructor Summary
BaseAdaptor(java.lang.String[] args)
          Constructs a BaseAdaptor.
 
Method Summary
 void compactStorage()
          Compact/cleanup the persistent storage for the adaptor.
 BundleFile createBundleFile(java.lang.Object content, BaseData data)
          Creates a bundle file object for the given content and base data.
 BundleData createSystemBundleData()
          Creates a BundleData object for the System Bundle.
 void frameworkStart(BundleContext fwContext)
          This method calls all the configured adaptor hook AdaptorHook.frameworkStart(BundleContext) methods.
 void frameworkStop(BundleContext fwContext)
          This method calls all the configured adaptor hook AdaptorHook.frameworkStop(BundleContext) methods.
 void frameworkStopping(BundleContext fwContext)
          This method calls all the configured adaptor hook AdaptorHook.frameworkStopping(BundleContext) methods.
 java.lang.ClassLoader getBundleClassLoaderParent()
          This method calls all the configured classloading hooks ClassLoadingHook.getBundleClassLoaderParent() methods until one returns a non-null value.
 BundleWatcher getBundleWatcher()
          Returns the bundle watcher for this FrameworkAdaptor.
 BundleContext getContext()
          Returns the system bundle's context
 EventPublisher getEventPublisher()
          Returns the event publisher for this BaseAdaptor
 FrameworkLog getFrameworkLog()
          This method calls all configured adaptor hook AdaptorHook.createFrameworkLog() methods until the first one returns a non-null value.
 HookRegistry getHookRegistry()
          Returns the HookRegistry object for this adaptor.
 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()
          This method will call all the configured adaptor hook AdaptorHook.addProperties(Properties) methods.
 ServiceRegistry getServiceRegistry()
          Returns the ServiceRegistry object which will be used to manage ServiceReference bindings.
 State getState()
          Returns the State for this FrameworkAdaptor.
protected  org.eclipse.osgi.internal.baseadaptor.BaseStorage getStorage()
           
 long getTotalFreeSpace()
          Returns the total amount of free space available for bundle storage on the device.
 void handleRuntimeError(java.lang.Throwable error)
          This method calls all the configured adaptor hooks AdaptorHook.handleRuntimeError(Throwable) methods.
 void initialize(EventPublisher publisher)
          This method will call all configured adaptor hooks AdaptorHook.initialize(BaseAdaptor) method.
 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.
 boolean isReadOnly()
          Returns true if the persistent storage is read-only
 boolean isStopping()
          Returns true if the frameworkStopping(BundleContext) method has been called
 java.net.URLConnection mapLocationToURLConnection(java.lang.String location)
          This method will call each configured adaptor hook AdaptorHook.mapLocationToURLConnection(String) method until one returns a non-null value.
 boolean matchDNChain(java.lang.String pattern, java.lang.String[] dnChain)
          This method calls all the configured adaptor hooks AdaptorHook.matchDNChain(String, String[]) methods until one returns a true value.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BaseAdaptor

public BaseAdaptor(java.lang.String[] args)
Constructs a BaseAdaptor.

Parameters:
args - arguments passed to the adaptor by the framework.
Method Detail

initialize

public void initialize(EventPublisher publisher)
This method will call all configured adaptor hooks AdaptorHook.initialize(BaseAdaptor) method.

Specified by:
initialize in interface FrameworkAdaptor
Parameters:
publisher - The EventPublisher used to publish any events to the framework.
See Also:
FrameworkAdaptor.initialize(EventPublisher)

initializeStorage

public void initializeStorage()
                       throws java.io.IOException
Description copied from interface: FrameworkAdaptor
Initialize the persistent storage for the adaptor.

Specified by:
initializeStorage in interface FrameworkAdaptor
Throws:
java.io.IOException - If the adaptor is unable to initialize the bundle storage.
See Also:
FrameworkAdaptor.initializeStorage()

compactStorage

public void compactStorage()
                    throws java.io.IOException
Description copied from interface: FrameworkAdaptor
Compact/cleanup the persistent storage for the adaptor.

Specified by:
compactStorage in interface FrameworkAdaptor
Throws:
java.io.IOException - If the adaptor is unable to compact the bundle storage.
See Also:
FrameworkAdaptor.compactStorage()

getProperties

public java.util.Properties getProperties()
This method will call all the configured adaptor hook AdaptorHook.addProperties(Properties) methods.

Specified by:
getProperties in interface FrameworkAdaptor
Returns:
The properties object for the adaptor.
See Also:
FrameworkAdaptor.getProperties()

getInstalledBundles

public BundleData[] getInstalledBundles()
Description copied from interface: FrameworkAdaptor
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.

Specified by:
getInstalledBundles in interface FrameworkAdaptor
Returns:
Array of installed BundleData objects, or null if none can be found.
See Also:
FrameworkAdaptor.getInstalledBundles()

mapLocationToURLConnection

public java.net.URLConnection mapLocationToURLConnection(java.lang.String location)
                                                  throws BundleException
This method will call each configured adaptor hook AdaptorHook.mapLocationToURLConnection(String) method until one returns a non-null value. If none of the adaptor hooks return a non-null value then the string is used to construct a new URL object to open a new url connection.

Specified by:
mapLocationToURLConnection in interface FrameworkAdaptor
Parameters:
location - of the bundle.
Returns:
URLConnection that represents the location.
Throws:
BundleException - if the mapping fails.
See Also:
FrameworkAdaptor.mapLocationToURLConnection(String)

installBundle

public BundleOperation installBundle(java.lang.String location,
                                     java.net.URLConnection source)
Description copied from interface: FrameworkAdaptor
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.

Specified by:
installBundle in interface FrameworkAdaptor
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.
See Also:
FrameworkAdaptor.installBundle(String, URLConnection)

updateBundle

public BundleOperation updateBundle(BundleData bundledata,
                                    java.net.URLConnection source)
Description copied from interface: FrameworkAdaptor
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.

Specified by:
updateBundle in interface FrameworkAdaptor
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.
See Also:
FrameworkAdaptor.updateBundle(BundleData, URLConnection)

uninstallBundle

public BundleOperation uninstallBundle(BundleData bundledata)
Description copied from interface: FrameworkAdaptor
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.

Specified by:
uninstallBundle in interface FrameworkAdaptor
Parameters:
bundledata - BundleData to uninstall.
Returns:
BundleOperation object to be used to complete the uninstall.
See Also:
FrameworkAdaptor.uninstallBundle(BundleData)

getTotalFreeSpace

public long getTotalFreeSpace()
                       throws java.io.IOException
Description copied from interface: FrameworkAdaptor
Returns the total amount of free space available for bundle storage on the device.

Specified by:
getTotalFreeSpace in interface FrameworkAdaptor
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
See Also:
FrameworkAdaptor.getTotalFreeSpace()

getPermissionStorage

public PermissionStorage getPermissionStorage()
                                       throws java.io.IOException
Description copied from interface: FrameworkAdaptor
Returns the PermissionStorage object which will be used to to manage the permission data.

Specified by:
getPermissionStorage in interface FrameworkAdaptor
Returns:
The PermissionStorage object for the adaptor.
Throws:
java.io.IOException
See Also:
FrameworkAdaptor.getPermissionStorage()

getServiceRegistry

public ServiceRegistry getServiceRegistry()
Description copied from interface: FrameworkAdaptor
Returns the ServiceRegistry object which will be used to manage ServiceReference bindings.

Specified by:
getServiceRegistry in interface FrameworkAdaptor
Returns:
The ServiceRegistry object for the adaptor.
See Also:
FrameworkAdaptor.getServiceRegistry()

frameworkStart

public void frameworkStart(BundleContext fwContext)
                    throws BundleException
This method calls all the configured adaptor hook AdaptorHook.frameworkStart(BundleContext) methods.

Specified by:
frameworkStart in interface FrameworkAdaptor
Parameters:
fwContext - The System Bundle's BundleContext.
Throws:
BundleException - on any error that may occur.
See Also:
FrameworkAdaptor.frameworkStart(BundleContext)

frameworkStop

public void frameworkStop(BundleContext fwContext)
                   throws BundleException
This method calls all the configured adaptor hook AdaptorHook.frameworkStop(BundleContext) methods.

Specified by:
frameworkStop in interface FrameworkAdaptor
Parameters:
fwContext - The System Bundle's BundleContext.
Throws:
BundleException - on any error that may occur.
See Also:
FrameworkAdaptor.frameworkStop(BundleContext)

frameworkStopping

public void frameworkStopping(BundleContext fwContext)
This method calls all the configured adaptor hook AdaptorHook.frameworkStopping(BundleContext) methods.

Specified by:
frameworkStopping in interface FrameworkAdaptor
Parameters:
fwContext - The System Bundle's BundleContext.
See Also:
FrameworkAdaptor.frameworkStopping(BundleContext)

getInitialBundleStartLevel

public int getInitialBundleStartLevel()
Description copied from interface: FrameworkAdaptor
Returns the initial bundle start level as maintained by this adaptor

Specified by:
getInitialBundleStartLevel in interface FrameworkAdaptor
Returns:
the initial bundle start level
See Also:
FrameworkAdaptor.getInitialBundleStartLevel()

setInitialBundleStartLevel

public void setInitialBundleStartLevel(int value)
Description copied from interface: FrameworkAdaptor
Sets the initial bundle start level

Specified by:
setInitialBundleStartLevel in interface FrameworkAdaptor
Parameters:
value - the initial bundle start level
See Also:
FrameworkAdaptor.setInitialBundleStartLevel(int)

getFrameworkLog

public FrameworkLog getFrameworkLog()
This method calls all configured adaptor hook AdaptorHook.createFrameworkLog() methods until the first one returns a non-null value. If none of the adaptor hooks return a non-null value then a framework log implementation which does nothing is returned.

Specified by:
getFrameworkLog in interface FrameworkAdaptor
Returns:
The FrameworkLog to be used by the Framework.
See Also:
FrameworkAdaptor.getFrameworkLog()

createSystemBundleData

public BundleData createSystemBundleData()
                                  throws BundleException
Description copied from interface: FrameworkAdaptor
Creates a BundleData object for the System Bundle. The BundleData returned will be used to define the System Bundle for the Framework.

Specified by:
createSystemBundleData in interface FrameworkAdaptor
Returns:
the BundleData for the System Bundle.
Throws:
BundleException - if any error occurs while creating the System BundleData.
See Also:
FrameworkAdaptor.createSystemBundleData()

getBundleWatcher

public BundleWatcher getBundleWatcher()
Description copied from interface: FrameworkAdaptor
Returns the bundle watcher for this FrameworkAdaptor.

Specified by:
getBundleWatcher in interface FrameworkAdaptor
Returns:
the bundle watcher for this FrameworkAdaptor.
See Also:
FrameworkAdaptor.getBundleWatcher()

getPlatformAdmin

public PlatformAdmin getPlatformAdmin()
Description copied from interface: FrameworkAdaptor
Returns the PlatformAdmin for this FrameworkAdaptor.

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

Specified by:
getPlatformAdmin in interface FrameworkAdaptor
Returns:
the PlatformAdmin for this FrameworkAdaptor.
See Also:
FrameworkAdaptor.getPlatformAdmin()

getState

public State getState()
Description copied from interface: FrameworkAdaptor
Returns the State for this FrameworkAdaptor.

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

Specified by:
getState in interface FrameworkAdaptor
Returns:
the State for this FrameworkAdaptor.
See Also:
FrameworkAdaptor.getState()

getBundleClassLoaderParent

public java.lang.ClassLoader getBundleClassLoaderParent()
This method calls all the configured classloading hooks ClassLoadingHook.getBundleClassLoaderParent() methods until one returns a non-null value.

Specified by:
getBundleClassLoaderParent in interface FrameworkAdaptor
Returns:
the parent ClassLoader for all BundleClassLoaders created.
See Also:
FrameworkAdaptor.getBundleClassLoaderParent()

handleRuntimeError

public void handleRuntimeError(java.lang.Throwable error)
This method calls all the configured adaptor hooks AdaptorHook.handleRuntimeError(Throwable) methods.

Specified by:
handleRuntimeError in interface FrameworkAdaptor
Parameters:
error - The Throwable for the runtime error that is to be handled.
See Also:
FrameworkAdaptor.handleRuntimeError(Throwable)

matchDNChain

public boolean matchDNChain(java.lang.String pattern,
                            java.lang.String[] dnChain)
This method calls all the configured adaptor hooks AdaptorHook.matchDNChain(String, String[]) methods until one returns a true value.

Specified by:
matchDNChain in interface FrameworkAdaptor
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.
See Also:
FrameworkAdaptor.matchDNChain(String, String[])

isStopping

public boolean isStopping()
Returns true if the frameworkStopping(BundleContext) method has been called

Returns:
true if the framework is stopping

getEventPublisher

public EventPublisher getEventPublisher()
Returns the event publisher for this BaseAdaptor

Returns:
the event publisher for this BaseAdaptor

getHookRegistry

public HookRegistry getHookRegistry()
Returns the HookRegistry object for this adaptor.

Returns:
the HookRegistry object for this adaptor.

getContext

public BundleContext getContext()
Returns the system bundle's context

Returns:
the system bundle's context

createBundleFile

public BundleFile createBundleFile(java.lang.Object content,
                                   BaseData data)
                            throws java.io.IOException
Creates a bundle file object for the given content and base data. This method must delegate to each configured bundle file factory BundleFileFactoryHook.createBundleFile(Object, BaseData, boolean) method until one factory returns a non-null value. If no bundle file factory returns a non-null value then the the default behavior will be performed.

If the specified content is null then the base content of the specified bundledata must be found before calling any bundle file factories.

After the bundle file has been created each configured bundle file wrapper factory BundleFileWrapperFactoryHook.wrapBundleFile(BundleFile, Object, BaseData, boolean) method is called to wrap the bundle file.

Parameters:
content - The object which contains the content of a bundle file. A value of null indicates that the storage must find the base content for the specified BaseData.
data - The BaseData associated with the content
Returns:
a BundleFile object.
Throws:
java.io.IOException - if an error occured while creating the BundleFile

isReadOnly

public boolean isReadOnly()
Returns true if the persistent storage is read-only

Returns:
true if the persistent storage is read-only

getStorage

protected org.eclipse.osgi.internal.baseadaptor.BaseStorage getStorage()