PersistenceManager


1   /**
2    * Copyright (C) 2001-2002
3    * - France Telecom R&D
4    * - Laboratoire Logiciels, Systemes, Reseaux - UMR 5526, CNRS-INPG-UJF
5    *
6    * This library is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public
8    * License as published by the Free Software Foundation; either
9    * version 2 of the License, or (at your option) any later version.
10   *
11   * This library is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   * Lesser General Public License for more details.
15   *
16   * You should have received a copy of the GNU Lesser General Public
17   * License along with this library; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   *
20   * Release: 1.0
21   *
22   * Authors:
23   *
24   */
25  
26  package org.objectweb.perseus.persistence.api;
27  
28  import org.objectweb.perseus.cache.api.CacheEntry;
29  
30  /**
31   *
32   * @author Luciano Garcia-Banuelos (Luciano.Garcia@imag.fr)
33   */
34  public interface PersistenceManager {
35      /**
36       * Given an object, this method creates the corresponding copy in
37       * permanent support.  At the same time, it  establishes a binding
38       * between the object in main-memory and the permanent copy.
39       * Roughly, the internal tasks include:
40       * - Reserving space on  permanent  support,
41       * - Establishing a binding between the object  in main memory and
42       * the permanent copy,
43       * - Marking the object as dirty, (internal  or by the concurrency
44       * control module?)
45       * - Adding the object to the cache
46       * @param context is an identifier of the execution context. It can be a
47       * transaction handle.
48       * @param  obj The  object  whose state  is  to  be copied  to
49       * @return the state associated to the working set
50       * @exception PersistenceException Whenever the object is invalid
51       * (e.g. NULL) or it has been previously bound to another oid.
52       */
53      State export(WorkingSet context, Object   obj) throws PersistenceException;
54  
55      /**
56       * This method permits to given some information to build the identifier of
57       * the new persistent object.
58       * @param context is an identifier of the execution context. It can be a
59       * transaction handle.
60       * @param  obj The  object  whose state  is  to  be copied  to
61       * @param hints can be used to build the identifier of the object.
62       * @return the state associated to the working set
63       * @exception PersistenceException Whenever the object is invalid
64       * (e.g. NULL) or it has been previously bound to another oid.
65       */
66      State export(WorkingSet context, Object   obj, Object   hints) throws PersistenceException;
67  
68      /**
69       * Deletes the binding between  an in main-memory object, and its
70       * corresponding copy  in permanent support. At the  same time, it
71       * frees (may be) the  space in the permanent support allocated to
72       * the permanent copy.
73       * @param context is an identifier of the execution context. It can be a
74       * transaction handle.
75       * @param  oid The  identifier of the  corresponding object  to be
76       * destroyed.
77       * @return the state associated to the working set
78       * @exception PersistenceException
79       */
80      State unexport(WorkingSet context, Object   oid) throws PersistenceException;
81  
82      /**
83       * Deletes the binding between  an in main-memory object, and its
84       * corresponding copy  in permanent support. At the  same time, it
85       * frees (may be) the  space in the permanent support allocated to
86       * the permanent copy.
87       * @param context is an identifier of the execution context. It can be a
88       * transaction handle.
89       * @param  ce The  identifier of the  corresponding object  to be
90       * destroyed.
91       * @return the state associated to the working set
92       * @exception PersistenceException
93       */
94      State unexport(WorkingSet context, CacheEntry ce) throws PersistenceException;
95  
96      /**
97       * This method retrieves a CacheEntry without checking if the persistent 
98       * object, exists. If the entry is already in the working or in the cache, 
99       * the found entry is returned. Otherwise a new CacheEntry is returned.
100      * This method does not permit an access to persistent data, because no
101      * intention has been declared. Then a call to readIntention or 
102      * writeIntention is required.
103      * 
104      * @param context is an identifier of the execution context. It can be a
105      * transaction handle.
106      * @param  oid The  identifier of the  corresponding object to find
107      */ 
108     CacheEntry getObjectById(WorkingSet context, Object   oid) throws PersistenceException;
109     
110     /**
111      * This method records an access intention to a data object in read mode.
112      * @param context is an identifier of the execution context. It can be a
113      * transaction handle.
114      * @param oid is the object identifier.
115      * @return the state associated to the working set
116      * @exception PersistenceException
117      */
118     State readIntention(WorkingSet context, Object   oid, Object   thinLock) throws PersistenceException;
119 
120     /**
121      * This method records an access intention to a data object in read mode.
122      * @param context is an identifier of the execution context. It can be a
123      * transaction handle.
124      * @param ce is the cache entry.
125      * @return the state associated to the working set
126      * @exception PersistenceException
127      */
128     State readIntention(WorkingSet context, CacheEntry ce, Object   thinLock) throws PersistenceException;
129 
130     /**
131      * This method records an access intention to a data object in write mode.
132      * @param context is an identifier of the execution context. It can be a
133      * transaction handle.
134      * @param oid is the object identifier.
135      * @return the state associated to the working set
136      * @exception PersistenceException
137      */
138     State writeIntention(WorkingSet context, Object   oid, Object   thinLock) throws PersistenceException;
139 
140     /**
141      * This method records an access intention to a data object in write mode.
142      * @param context is an identifier of the execution context. It can be a
143      * transaction handle.
144      * @param ce is the cache entry.
145      * @return the state associated to the working set
146      * @exception PersistenceException
147      */
148     State writeIntention(WorkingSet context, CacheEntry ce, Object   thinLock) throws PersistenceException;
149 
150     /**
151      * This method can be used to mark the end of an access to a data object.
152      * @param context is an identifier of the execution context. It can be a
153      * transaction handle.
154      * @param ce is the  cache entry on which the access is finished.
155      * @exception PersistenceException
156      */
157     void accessCompletion(WorkingSet context, State ce) throws PersistenceException;
158 
159     /**
160      * This method permits to flush entries associated to a context.
161      * @param context is an identifier of the execution context. It can be a
162      * transaction handle.
163      * @param statefilter is a filter of the cache entry which must be flushed.
164      * A null StateFilter means all entries associated to the context has to be
165      * flushed. 
166      * @throws PersistenceException if the context is not valid.
167      */
168     void flush(WorkingSet context, StateFilter statefilter) throws PersistenceException;
169 
170     /**
171      * This method permits to flush entries associated to a context.
172      * @param context is an identifier of the execution context. It can be a
173      * transaction handle.
174      * @param state is the state taht must be flushed
175      * @throws PersistenceException if the context is not valid.
176      */
177     void flush(WorkingSet context, State state) throws PersistenceException;
178     
179     /**
180      * This methods permits to force the cache eviction of a persistent object
181      * designed by its identifier.
182      * @param context is the working set asking the eviction.
183      * @param oid is the identifier of the persistent object to evict from the
184      * cache
185      * @param force indicates if the entry MUST be evicted (true) or TRIES to be
186      * evicted (false).
187      * @return true if the entry has been evicted from the cache, otherwise false
188      * @throws PersistenceException if the instance is dirty or used by other
189      * working set.
190      */
191     boolean evict(WorkingSet context, Object   oid, boolean force)
192             throws PersistenceException;
193 
194     /**
195      * This methods permits to try the cache eviction of all persistent object
196      * @return the number of entry staying in the cache (not evicted)
197      */
198     int evictAll(WorkingSet context, boolean force) throws PersistenceException;
199 
200     /**
201      * Detach a persistent object from the persistent support. After calling
202      * this method the persistent object is no more associated to the context
203      * and this instance is no more in the cache. If the persistent object has
204      * been modified, it is flushed. Be carefull the lock for the concurrency
205      * (read | write) is kept until the end of the context.
206      *
207      * @param ws is the current working set
208      * @param oid is the identifier of the persistent object
209      * @throws PersistenceException
210      */
211     void unbind(WorkingSet ws, Object   oid) throws PersistenceException;
212 
213     /**
214      * Detach a persistent object from the persistent support. After calling
215      * this method the persistent object is no more associated to the context
216      * and this instance is no more in the cache. If the persistent object has
217      * been modified, it is flushed. Be carefull the lock for the concurrency
218      * (read | write) is kept until the end of the context.
219      *
220      * @param ws is the current working set
221      * @param ce is the cache entry of the persistent object
222      * @throws PersistenceException
223      */
224     void unbind(WorkingSet ws, CacheEntry ce) throws PersistenceException;
225 
226     /**
227      * Forget modifications of a dirty persistent object. The state is re-read
228      * from the cache or later from the database. Be carefull the lock for
229      * the concurrency (read | write) is kept until the end of the context.
230      *
231      * @param ws is the current working set
232      * @param oid is the identifier of the persistent object
233      * @throws PersistenceException
234      */
235     void refresh(WorkingSet ws, Object   oid) throws PersistenceException;
236 
237     /**
238      * Forget modifications of a dirty persistent object. The state is re-read
239      * from the cache or later from the database. Be carefull the lock for
240      * the concurrency (read | write) is kept until the end of the context.
241      *
242      * @param ws is the current working set
243      * @param ce is the cache entry of the persistent object
244      * @throws PersistenceException
245      */
246     void refresh(WorkingSet ws, CacheEntry ce) throws PersistenceException;
247 
248     /**
249      * creates a working set
250      * @param userObject can be an external user depending on the
251      * personnality.
252      * @return a new WorkingSet
253      * @throws PersistenceException
254      */
255     WorkingSet createWS(Object   userObject)
256             throws PersistenceException;
257 
258     /**
259      * creates a working set
260      * @param userObject can be an external user depending on the
261      * personnality.
262      * @param workingSetType is a type of the working set.
263      * @return a new WorkingSet
264      * @throws PersistenceException
265      */
266     WorkingSet createWS(Object   userObject,
267                         Object   workingSetType)
268             throws PersistenceException;
269 
270     /**
271      * Closes and releases a context.
272      * @param context which must be closed
273      * @throws PersistenceException if the context is a transactional context
274      * which has not been commited or aborted.
275      */
276     void close(WorkingSet context) throws PersistenceException;
277 
278 }
279
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags