StorageHook


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.osgi.baseadaptor.hooks;
13  
14  import java.io.*;
15  import java.util.Dictionary  ;
16  import org.eclipse.osgi.baseadaptor.BaseData;
17  import org.eclipse.osgi.framework.adaptor.BundleData;
18  import org.eclipse.osgi.framework.util.KeyedElement;
19  import org.osgi.framework.BundleException;
20  
21  /**
22   * A StorageHook hooks into the persistent storage loading and saving.  A StorageHook gets 
23   * associated with each BaseData object installed in the adaptor.<p>
24   * A StorageHook extends {@link KeyedElement}, the key used for the element must be the 
25   * fully qualified string name of the StorageHook implementation class.
26   * @see BaseData#getStorageHook(String)
27   * @since 3.2
28   */
29  public interface StorageHook extends KeyedElement {
30      /**
31       * Returns the storage version of this storage hook.  This version 
32       * is used by the storage to check the consistency of cached persistent 
33       * data.  Any time a storage hook changes the format of its persistent 
34       * data the storage version should be incremented. 
35       * @return the storage version of this storage hook
36       */
37      int getStorageVersion();
38  
39      /**
40       * Creates an uninitialized storage hook for the specified bundledata.  This method 
41       * is called when a bundle is installed or updated.  The returned storage hook will be 
42       * used for the new contents of the bundle.  The returned hook will have its 
43       * {@link #initialize(Dictionary)} method called to initialize the storage hook.
44       * @param bundledata a base data the created storage hook will be associated with
45       * @return an uninitialized storage hook
46       * @throws BundleException if any error occurs
47       */
48      StorageHook create(BaseData bundledata) throws BundleException;
49  
50      /**
51       * Initializes this storage hook with the content of the specified bundle manifest.  
52       * This method is called when a bundle is installed or updated.
53       * @see #create(BaseData)
54       * @see #copy(StorageHook)
55       * @param manifest the bundle manifest to load into this storage hook
56       * @throws BundleException if any error occurs
57       */
58      void initialize(Dictionary   manifest) throws BundleException;
59  
60      /**
61       * Creates a new storage hook and loads the data from the specified 
62       * input stream into the storage hook.  This method is called during startup to 
63       * load all the persistently installed bundles. <p>
64       * It is important that this method and the {@link #save(DataOutputStream)} method 
65       * stay in sync.  This method must be able to successfully read the data saved by the
66       * {@link #save(DataOutputStream)} method.
67       * @param bundledata a base data the loaded storage hook will be associated with
68       * @param is an input stream used to load the storage hook's data from.
69       * @return a loaded storage hook
70       * @see #save(DataOutputStream)
71       * @throws IOException if any error occurs
72       */
73      StorageHook load(BaseData bundledata, DataInputStream is) throws IOException;
74  
75      /**
76       * Saves the data from this storage hook into the specified output stream.  This method
77       * is called if some persistent data has changed for the bundle. <p>
78       * It is important that this method and the {@link #load(BaseData, DataInputStream)}
79       * method stay in sync.  This method must be able to save data which the 
80       * {@link #load(BaseData, DataInputStream)} method can ready successfully.
81       * @see #load(BaseData, DataInputStream)
82       * @param os an output stream used to save the storage hook's data from.
83       * @throws IOException if any error occurs
84       */
85      void save(DataOutputStream os) throws IOException;
86  
87      /**
88       * Copies the data from the specified storage hook into this storage hook.  This method 
89       * is called when a bundle is updated to copy the data from the original bundle to a 
90       * new storage hook.  Then this storage will be initialized with the new bundle's 
91       * manifest using the {@link #initialize(Dictionary)} method.
92       * @see #create(BaseData)
93       * @see #initialize(Dictionary)
94       * @param storageHook the original storage hook to copy data out of.
95       */
96      void copy(StorageHook storageHook);
97  
98      /**
99       * Validates the data in this storage hook, if the data is invalid then an illegal state 
100      * exception is thrown
101      * @throws IllegalArgumentException if the data is invalid
102      */
103     void validate() throws IllegalArgumentException  ;
104 
105     /**
106      * Returns the manifest for the data in this storage hook, or null if this hook does
107      * not provide the manifest.  Most hooks should return null from this method.  This 
108      * method may be used to provide special handling of manifest loading.  For example,
109      * to provide a cached manfest or to do automatic manifest generation.
110      * @param firstLoad true if this is the very first time this manifest is being loaded.
111      * @return the manifest for the data in this storage hook, or null if this hook does
112      * not provide the manifest
113      * @throws BundleException 
114      */
115     Dictionary   getManifest(boolean firstLoad) throws BundleException;
116 
117     /**
118      * Gets called by a base data during {@link BundleData#setStatus(int)}.
119      * A base data will call this method for each configured storage hook it
120      * is associated with until one storage hook returns true.  If all configured storage 
121      * hooks return false then the BaseData will be marked dirty and will cause the 
122      * status to be persistently saved.
123      * @param status the new status of the base data
124      * @return false if the status is not to be persistently saved; otherwise true is returned
125      */
126     boolean forgetStatusChange(int status);
127 
128     /**
129      * Gets called by a base data during {@link BundleData#setStartLevel(int)}.
130      * A base data will call this method for each configured storage hook it
131      * is associated with until one storage hook returns true.  If all configured storage 
132      * hooks return false then the BaseData will be marked dirty and will cause the 
133      * start level to be persistently saved.
134      * @param startlevel the new startlevel of the base data
135      * @return false if the startlevel is not to be persistently saved; otherwise true is returned
136      */
137     boolean forgetStartLevelChange(int startlevel);
138 
139     /**
140      * Gets called by a base data during {@link BundleData#matchDNChain(String)}.
141      * A base data will call this method for each configured storage hook it
142      * is associated with until one storage hook returns true.  If all configured storage 
143      * hooks return false value then the BaseAdaptor will return false.
144      * @param pattern the pattern of distinguished name (DN) chains to match
145      * @return true if the pattern matches. A value of false is returned
146      * if bundle signing is not supported.
147      */
148     boolean matchDNChain(String   pattern);
149 }
150
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags