StateManager


1   /**
2    * Copyright (C) 2001-2003 France Telecom R&D
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
17   */
18  package org.objectweb.perseus.persistence.api;
19  
20  import org.objectweb.perseus.cache.api.CacheEntry;
21  import org.objectweb.perseus.cache.api.CacheEventListener;
22  
23  /**
24   * A StateManager is used by the PersistenceManager and the ConcurrencyManager
25   * in order to manage the life cycle of cache entries and their states. This
26   * management concerns the java life cycle of the state instance (create,
27   * destroy) and the status (dirty, new, deleted, ...).  
28   * This interface is implemented by the Personality using the persistence
29   * framework of Perseus.
30   * @author S.Chassande-Barrioz
31   */
32  public interface StateManager extends CacheEventListener {
33  
34      /**
35       * Creates a new State.
36       * @return a State instance linked to its cache entry (ie the
37       * state.getCacheEntry() must return 'ce')
38       */
39      State createState(CacheEntry ce);
40  
41      /**
42       * Creates a new State.
43       * @param s the state to clone
44       * @return a new state which contains the same values (data and cache entry
45       * reference) than the existing state given in parameter
46       */
47      State createState(State s);
48  
49      /**
50       * @param ce is the cache entry when the reference state is asked
51       * @return the reference state of a cache entry. If no reference state
52       * exists, the 'null' value is retrieved.
53       */
54      State getReferenceState(CacheEntry ce);
55  
56      /**
57       * Assignes the reference state to a cache entry
58       * @param ce is the cache entry which the reference state must be changed
59       * @param state is the new value of the reference state. If this parameter
60       * is null, that means the CacheEntry does not have a state in memory, it
61       * is hollow.
62       */
63      void setReferenceState(CacheEntry ce, State state);
64  
65      /**
66       * Removes a state. In general this method does nothing, but it can be used
67       * as a listener.
68       * @param state the state to destroy
69       */
70      void destroyState(State state);
71  
72      /**
73       * Marks the status of the state to 'unexported' (deleted).
74       */
75      void makeUnexported(State state);
76  
77      /**
78       * @return true if the state has been marked as unexported, otherwise false
79       * The state is unexported if the makeUnexported method has been called.
80       */
81      boolean isUnexported(State state);
82  
83      /**
84       * Marks the status of the state to 'exported' (created).
85       */
86      void makeExported(State state);
87  
88      /**
89       * @return true if the state has been marked as exported, otherwise false
90       * The state is exported if the makeExported method has been called.
91       */
92      boolean isExported(State state);
93  
94      /**
95       * Marks the status of the state to 'dirty' (modified). The next calls to
96       * isflushed will return false.
97       */
98      void makeDirty(State state);
99  
100     /**
101      * @return true if the state has been marked as dirty, otherwise false
102      * The state is dirty if the makeDirty or makeExported or makeUnexported
103      * method has been called.
104      */
105     boolean isDirty(State state);
106 
107     /**
108      * Marks the status of the state to 'clean' (non modified). This method is
109      * used at the commit of a working set in order to reset the state status.
110      */
111     void makeClean(State state);
112 
113     /**
114      * Marks the status of the state to 'flushed' (written on data support).
115      * @param state
116      */
117     void makeFlushed(State state);
118 
119     /**
120      * @return true if the state has been marked as flushed without call to
121      * makeDirty, otherwise false
122      */
123     boolean isFlushed(State state);
124 
125     /**
126      * A persistent object has been removed or evicted from the cache, then
127      * it must be marked as non persistent
128      * @param ce is the cache entry referenced the persistent object to unbind
129      */
130     void makeUnbound(CacheEntry ce);
131 
132     /**
133      * A persistent object has been removed or evicted from the cache, then
134      * it must be marked as non persistent
135      * @param ce is the cache entry referenced the persistent object to bind
136      * @param oid is the id of the cache entry to bind 
137      */
138     void makeBound(CacheEntry ce, Object   oid);
139     
140     /**
141      * @return true if the persistent object referenced by the given cache
142      * entry, is persistent.
143      */
144     boolean isBound(CacheEntry ce);
145     
146     /**
147      * Indicates if a State has to be merged at commit time with the reference
148      * state
149      */
150     boolean isToMerge(State state);
151     
152     /**
153      * Marks the flag 'toMerge' on a state. a true value indicates that the
154      * state has to be merged at commit time, with the reference state. 
155      * @param state
156      * @param thinLock is a hints describing  the thinlock causing the merge
157      * at commit time.
158      */
159     void makeToMerge(State state, Object   thinLock);
160     
161     /**
162      * Merges a state (newState) into a oldSate. 
163      * @param oldState is the state wich will contains the delta of the newState
164      * @param newState contains the delta to merge to the oldState
165      * @returnis the result of the merge operation  
166      */
167     State merge(State oldState, State newState);
168 
169     /**
170      * Indicates that this state is no more used by any working set. This event
171      * permit for instance to unswizzle the references to persistent objects 
172      * from the state.
173      * @param state is the state that is not used by any working set
174      */
175     void stateNoMoreUsed(State state);
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags