001: /**
002: * Speedo: an implementation of JDO compliant personality on top of JORM generic
003: * I/O sub-system.
004: * Copyright (C) 2001-2004 France Telecom R&D
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation; either
009: * version 2 of the License, or (at your option) any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: * You should have received a copy of the GNU Lesser General Public
017: * License along with this library; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: *
020: *
021: *
022: * Contact: speedo@objectweb.org
023: *
024: * Authors: S.Chassande-Barrioz.
025: *
026: */package org.objectweb.speedo.mim.api;
027:
028: import org.objectweb.speedo.pm.api.POManagerItf;
029: import org.objectweb.jorm.api.PAccessor;
030: import java.io.Serializable;
031: import java.util.Collection;
032: import java.util.Map;
033:
034: /**
035: * This interface a state of an user instance.
036: *
037: * @author S.Chassande-Barrioz
038: */
039: public interface StateItf extends PAccessor,
040: org.objectweb.perseus.persistence.api.State, Serializable {
041:
042: /**
043: * Changes the status of this object
044: *
045: * @see org.objectweb.speedo.mim.api.LifeCycle
046: * @param action the action that may change the status
047: */
048: void speedoChangeStatus(byte action);
049:
050: /**
051: * Gets the current status of this object
052: *
053: * @see org.objectweb.speedo.mim.api.LifeCycle
054: * @return the current state in the life cycle
055: */
056: byte speedoGetStatus();
057:
058: /**
059: * Forces the new value of the status
060: *
061: * @see org.objectweb.speedo.mim.api.LifeCycle
062: * @param newValue the new status of this object
063: */
064: void speedoSetStatus(byte newValue);
065:
066: /**
067: * Version management:
068: * strategies supported are:
069: * - date-time
070: * - version-number
071: *
072: */
073:
074: /**
075: * change the version of this only if needed
076: * The version is computed by this method
077: * A call to changeVersion can have no effect.
078: */
079: void speedoChangeVersion();
080:
081: /**
082: * Return the version of the object as a long
083: */
084: long getVersion();
085:
086: /**
087: * check the validity of the version of sa compared to the persistent object this.
088: */
089: boolean checkVersion(StateItf sa);
090:
091: /**
092: * Gets the current status of this detached object
093: *
094: * @return the current state in the life cycle
095: */
096: byte getDetachedStatus();
097:
098: /**
099: * Forces the new value of the detached status
100: *
101: * @param newValue the new status of this object
102: */
103: void setDetachedStatus(byte newValue);
104:
105: /**
106: * @return The PersistentObjectItf attached to this state representation.
107: */
108: PersistentObjectItf getSpeedoPO();
109:
110: /**
111: * Assignes the PersistentObjectItf attached to this state representation.
112: */
113: void setSpeedoPO(PersistentObjectItf sp);
114:
115: /**
116: * Prepare to write (relations consistency management)
117: */
118: void prepareWrite();
119:
120: /**
121: * The context has been closed (ex: transaction end).
122: */
123: void workingSetClosed();
124:
125: /**
126: * indicates if the object has been flushed on the support in a writing
127: * before the end of the working set (commit | rollback | close).
128: */
129: boolean hasBeenFlush();
130:
131: /**
132: * Assignates a boolean value to indicate if the object has been flushed
133: * on the support in a writing before the end of the working
134: * set (commit | rollback | close).
135: * @param val is the boolean which must be assigned.
136: */
137: void setFlushed(boolean val);
138:
139: /**
140: * Makes persistent all inner elements of the persistent instance. For a
141: * class, it means making persistent all objects referenced by a persistent
142: * field. For a genclass it means making persistent element of the genclass.
143: * This method is called when a makePersistent is called on the persistent
144: * class (PO) linked to this accessor.
145: * @param pm is the po manager for making persistent inner element.
146: */
147: void makePersistent(POManagerItf pm);
148:
149: /**
150: * makes persistent on attach, taking into account the map
151: * representing the attch context.
152: * It enables to avoid cycles.
153: * @param pm is the po manager for making persistent inner element.
154: * @param map is the context of the attachment process.
155: */
156: void makePersistentOnAttach(POManagerItf pm, Map map);
157:
158: /**
159: * Deletes persistent all inner elements of the persistent instance. For a
160: * class, it means deleting persistent all objects referenced by a persistent
161: * field. For a genclass it means deleting persistent element of the genclass.
162: * This method is called when a deletePersistent is called on the persistent
163: * class (po) linked to this accessor.
164: * @param pm is the po manager for making persistent inner element.
165: */
166: void deletePersistent(POManagerItf pm);
167:
168: /**
169: * Askes the loading of the some fields identified by the long array.
170: * @param pm is the po manager to use to load references
171: * @param fields is an array of long. Each long is a bit mask indicating
172: * fields to load. As a long is stored over 64 bits, each long of the array
173: * can represent only 64 persistent fields. If the class has 70 persistent
174: * field, the parameter could be a long array size is 2. This parameter
175: * can be null if no field loading is required.
176: */
177: void loadFields(POManagerItf pm, long[] fields);
178:
179: /**
180: * This method is used during the detach operation. A call to this method
181: * copy the field of the state into the the cloned state. When a field
182: * references a persistent object, according to the fetch plan, the
183: * referenced can be detached too.
184: * @param pm is the po manager used during the detach operation
185: * @param map is the map of the detached object. The use of this map permits
186: * to support cycle in the object graph.
187: * @param clone is a clone of the current state
188: * @param fgHints represents the fetch plan.
189: */
190: void detachCopy(POManagerItf pm, Map map, StateItf clone,
191: Collection fgHints);
192:
193: /**
194: * This method is used during the attach operation. A call to this method
195: * copy the field of the cloned state into the the current state. When a field
196: * references a persistent object, according to the fetch plan, the
197: * referenced can be attached too.
198: * @param pm is the po manager used during the attach operation
199: * @param map is the map of the atttached object. The use of this map permits
200: * to support cycle in the object graph.
201: * @param detached is the detached state used to update the current state
202: */
203: void attachCopy(POManagerItf pm, Map map, StateItf detached);
204:
205: /**
206: * This method is used during the refresh operation. A call to this method
207: * refreshes the fields of the current state. When a field
208: * references a persistent object, according to the fetch plan, the
209: * referenced can be refreshed too.
210: * @param pm is the po manager used during the refresh operation
211: * @param map is the map of the refreshed object. The use of this map permits
212: * to support cycle in the object graph.
213: * @param fgHints represents the fetch plan.
214: */
215: void refresh(POManagerItf pm, Map map, Collection fgHints);
216:
217: /**
218: * This method is used during the retrieve operation. A call to this method
219: * retrieves the fields of the current state. When a field
220: * references a persistent object, according to the fetch plan, the
221: * referenced can be retrieved too.
222: * @param pm is the po manager used during the retrieve operation
223: * @param map is the map of the retrieved object. The use of this map permits
224: * to support cycle in the object graph.
225: * @param fgHints represents the fetch plan.
226: */
227: void retrieve(POManagerItf pm, Map map, Collection fgHints);
228:
229: /**
230: * Force the detached status to DETACHED_DIRTY and
231: * all the xxxLoaded to true
232: */
233: void forceDetachedDirty();
234:
235: /**
236: * Restore the detached status to DETACHED_NONE and
237: * all the xxxLoaded to false
238: */
239: void restoreDetachedNone();
240:
241: /**
242: * indicates if the StateItf has to be merge with the reference state at commit
243: * time.
244: */
245: boolean isToMerge();
246:
247: /**
248: * Mark the current state with the flag 'toMerge'. This status means at
249: * commit time this state has to be merge with the referenceState (cache).
250: * Since this method call and until the transaction end, the implementation
251: * could register the change for the merge.
252: *
253: * @param thinLock is an object representing the thin lock
254: */
255: void makeToMerge(Object thinLock);
256:
257: /**
258: * This action updates the old state with the change (delta) done in the
259: * transaction on this state.
260: * @param oldState is the state which has to be updated
261: * @return the updated state.
262: */
263: org.objectweb.perseus.persistence.api.State merge(
264: org.objectweb.perseus.persistence.api.State oldState);
265:
266: void unSwizzle();
267:
268: /**
269: * The field uses in user cache, has been modified.
270: * @param cacheId is the cache identifier. The value Integer.MAX_VALUE
271: * means that all user cache must be updated.
272: * @param rebind if true, the speedoAcessor is rebound
273: */
274: void indexFieldModified(int cacheId, boolean rebind);
275: }
|