org.eclipse.osgi.baseadaptor.hooks
Interface StorageHook

All Superinterfaces:
KeyedElement
All Known Implementing Classes:
EclipseStorageHook

public interface StorageHook
extends KeyedElement

A StorageHook hooks into the persistent storage loading and saving. A StorageHook gets associated with each BaseData object installed in the adaptor.

A StorageHook extends KeyedElement, the key used for the element must be the fully qualified string name of the StorageHook implementation class.

Since:
3.2
See Also:
BaseData.getStorageHook(String)

Method Summary
 void copy(StorageHook storageHook)
          Copies the data from the specified storage hook into this storage hook.
 StorageHook create(BaseData bundledata)
          Creates an uninitialized storage hook for the specified bundledata.
 boolean forgetStartLevelChange(int startlevel)
          Gets called by a base data during BundleData.setStartLevel(int).
 boolean forgetStatusChange(int status)
          Gets called by a base data during BundleData.setStatus(int).
 java.util.Dictionary getManifest(boolean firstLoad)
          Returns the manifest for the data in this storage hook, or null if this hook does not provide the manifest.
 int getStorageVersion()
          Returns the storage version of this storage hook.
 void initialize(java.util.Dictionary manifest)
          Initializes this storage hook with the content of the specified bundle manifest.
 StorageHook load(BaseData bundledata, java.io.DataInputStream is)
          Creates a new storage hook and loads the data from the specified input stream into the storage hook.
 boolean matchDNChain(java.lang.String pattern)
          Gets called by a base data during BundleData.matchDNChain(String).
 void save(java.io.DataOutputStream os)
          Saves the data from this storage hook into the specified output stream.
 void validate()
          Validates the data in this storage hook, if the data is invalid then an illegal state exception is thrown
 
Methods inherited from interface org.eclipse.osgi.framework.util.KeyedElement
compare, getKey, getKeyHashCode
 

Method Detail

getStorageVersion

int getStorageVersion()
Returns the storage version of this storage hook. This version is used by the storage to check the consistency of cached persistent data. Any time a storage hook changes the format of its persistent data the storage version should be incremented.

Returns:
the storage version of this storage hook

create

StorageHook create(BaseData bundledata)
                   throws BundleException
Creates an uninitialized storage hook for the specified bundledata. This method is called when a bundle is installed or updated. The returned storage hook will be used for the new contents of the bundle. The returned hook will have its initialize(Dictionary) method called to initialize the storage hook.

Parameters:
bundledata - a base data the created storage hook will be associated with
Returns:
an uninitialized storage hook
Throws:
BundleException - if any error occurs

initialize

void initialize(java.util.Dictionary manifest)
                throws BundleException
Initializes this storage hook with the content of the specified bundle manifest. This method is called when a bundle is installed or updated.

Parameters:
manifest - the bundle manifest to load into this storage hook
Throws:
BundleException - if any error occurs
See Also:
create(BaseData), copy(StorageHook)

load

StorageHook load(BaseData bundledata,
                 java.io.DataInputStream is)
                 throws java.io.IOException
Creates a new storage hook and loads the data from the specified input stream into the storage hook. This method is called during startup to load all the persistently installed bundles.

It is important that this method and the save(DataOutputStream) method stay in sync. This method must be able to successfully read the data saved by the save(DataOutputStream) method.

Parameters:
bundledata - a base data the loaded storage hook will be associated with
is - an input stream used to load the storage hook's data from.
Returns:
a loaded storage hook
Throws:
java.io.IOException - if any error occurs
See Also:
save(DataOutputStream)

save

void save(java.io.DataOutputStream os)
          throws java.io.IOException
Saves the data from this storage hook into the specified output stream. This method is called if some persistent data has changed for the bundle.

It is important that this method and the load(BaseData, DataInputStream) method stay in sync. This method must be able to save data which the load(BaseData, DataInputStream) method can ready successfully.

Parameters:
os - an output stream used to save the storage hook's data from.
Throws:
java.io.IOException - if any error occurs
See Also:
load(BaseData, DataInputStream)

copy

void copy(StorageHook storageHook)
Copies the data from the specified storage hook into this storage hook. This method is called when a bundle is updated to copy the data from the original bundle to a new storage hook. Then this storage will be initialized with the new bundle's manifest using the initialize(Dictionary) method.

Parameters:
storageHook - the original storage hook to copy data out of.
See Also:
create(BaseData), initialize(Dictionary)

validate

void validate()
              throws java.lang.IllegalArgumentException
Validates the data in this storage hook, if the data is invalid then an illegal state exception is thrown

Throws:
java.lang.IllegalArgumentException - if the data is invalid

getManifest

java.util.Dictionary getManifest(boolean firstLoad)
                                 throws BundleException
Returns the manifest for the data in this storage hook, or null if this hook does not provide the manifest. Most hooks should return null from this method. This method may be used to provide special handling of manifest loading. For example, to provide a cached manfest or to do automatic manifest generation.

Parameters:
firstLoad - true if this is the very first time this manifest is being loaded.
Returns:
the manifest for the data in this storage hook, or null if this hook does not provide the manifest
Throws:
BundleException

forgetStatusChange

boolean forgetStatusChange(int status)
Gets called by a base data during BundleData.setStatus(int). A base data will call this method for each configured storage hook it is associated with until one storage hook returns true. If all configured storage hooks return false then the BaseData will be marked dirty and will cause the status to be persistently saved.

Parameters:
status - the new status of the base data
Returns:
false if the status is not to be persistently saved; otherwise true is returned

forgetStartLevelChange

boolean forgetStartLevelChange(int startlevel)
Gets called by a base data during BundleData.setStartLevel(int). A base data will call this method for each configured storage hook it is associated with until one storage hook returns true. If all configured storage hooks return false then the BaseData will be marked dirty and will cause the start level to be persistently saved.

Parameters:
startlevel - the new startlevel of the base data
Returns:
false if the startlevel is not to be persistently saved; otherwise true is returned

matchDNChain

boolean matchDNChain(java.lang.String pattern)
Gets called by a base data during BundleData.matchDNChain(String). A base data will call this method for each configured storage hook it is associated with until one storage hook returns true. If all configured storage hooks return false value then the BaseAdaptor will return false.

Parameters:
pattern - the pattern of distinguished name (DN) chains to match
Returns:
true if the pattern matches. A value of false is returned if bundle signing is not supported.