/*******************************************************************************
* Copyright (c) 2005, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.osgi.baseadaptor.hooks;
import java.io.*;
import java.util.Dictionary;
import org.eclipse.osgi.baseadaptor.BaseData;
import org.eclipse.osgi.framework.adaptor.BundleData;
import org.eclipse.osgi.framework.util.KeyedElement;
import org.osgi.framework.BundleException;
/**
* A StorageHook hooks into the persistent storage loading and saving. A StorageHook gets
* associated with each BaseData object installed in the adaptor.<p>
* A StorageHook extends {@link KeyedElement}, the key used for the element must be the
* fully qualified string name of the StorageHook implementation class.
* @see BaseData#getStorageHook(String)
* @since 3.2
*/
public interface StorageHook extends KeyedElement {
/**
* 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.
* @return the storage version of this storage hook
*/
int getStorageVersion();
/**
* 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
* {@link #initialize(Dictionary)} method called to initialize the storage hook.
* @param bundledata a base data the created storage hook will be associated with
* @return an uninitialized storage hook
* @throws BundleException if any error occurs
*/
StorageHook create(BaseData bundledata) 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.
* @see #create(BaseData)
* @see #copy(StorageHook)
* @param manifest the bundle manifest to load into this storage hook
* @throws BundleException if any error occurs
*/
void initialize(Dictionary<String, String> manifest) throws BundleException;
/**
* 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. <p>
* It is important that this method and the {@link #save(DataOutputStream)} method
* stay in sync. This method must be able to successfully read the data saved by the
* {@link #save(DataOutputStream)} method.
* @param bundledata a base data the loaded storage hook will be associated with
* @param is an input stream used to load the storage hook's data from.
* @return a loaded storage hook
* @see #save(DataOutputStream)
* @throws IOException if any error occurs
*/
StorageHook load(BaseData bundledata, DataInputStream is) throws 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. <p>
* It is important that this method and the {@link #load(BaseData, DataInputStream)}
* method stay in sync. This method must be able to save data which the
* {@link #load(BaseData, DataInputStream)} method can ready successfully.
* @see #load(BaseData, DataInputStream)
* @param os an output stream used to save the storage hook's data from.
* @throws IOException if any error occurs
*/
void save(DataOutputStream os) throws IOException;
/**
* 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 {@link #initialize(Dictionary)} method.
* @see #create(BaseData)
* @see #initialize(Dictionary)
* @param storageHook the original storage hook to copy data out of.
*/
void copy(StorageHook storageHook);
/**
* Validates the data in this storage hook, if the data is invalid then an illegal state
* exception is thrown
* @throws IllegalArgumentException if the data is invalid
*/
void validate() throws IllegalArgumentException;
/**
* 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.
* @param firstLoad true if this is the very first time this manifest is being loaded.
* @return the manifest for the data in this storage hook, or null if this hook does
* not provide the manifest
* @throws BundleException
*/
Dictionary<String, String> getManifest(boolean firstLoad) throws BundleException;
/**
* Gets called by a base data during {@link 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.
* @param status the new status of the base data
* @return false if the status is not to be persistently saved; otherwise true is returned
*/
boolean forgetStatusChange(int status);
/**
* Gets called by a base data during {@link 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.
* @param startlevel the new startlevel of the base data
* @return false if the startlevel is not to be persistently saved; otherwise true is returned
*/
boolean forgetStartLevelChange(int startlevel);
}