001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * // Copyright (c) 1998, 2007, Oracle. All rights reserved.
005: *
006: *
007: * The contents of this file are subject to the terms of either the GNU
008: * General Public License Version 2 only ("GPL") or the Common Development
009: * and Distribution License("CDDL") (collectively, the "License"). You
010: * may not use this file except in compliance with the License. You can obtain
011: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
012: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
013: * language governing permissions and limitations under the License.
014: *
015: * When distributing the software, include this License Header Notice in each
016: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
017: * Sun designates this particular file as subject to the "Classpath" exception
018: * as provided by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the License
020: * Header, with the fields enclosed by brackets [] replaced by your own
021: * identifying information: "Portions Copyrighted [year]
022: * [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * If you wish your version of this file to be governed by only the CDDL or
027: * only the GPL Version 2, indicate your decision by adding "[Contributor]
028: * elects to include this software in this distribution under the [CDDL or GPL
029: * Version 2] license." If you don't indicate a single choice of license, a
030: * recipient has the option to distribute your version of this file under
031: * either the CDDL, the GPL Version 2 or to extend the choice of license to
032: * its licensees as provided above. However, if you add GPL Version 2 code
033: * and therefore, elected the GPL Version 2 license, then the option applies
034: * only if the new code is made subject to such option by the copyright
035: * holder.
036: */
037: package oracle.toplink.essentials.internal.descriptors;
038:
039: import java.io.Serializable;
040: import java.util.Vector;
041: import oracle.toplink.essentials.expressions.*;
042: import oracle.toplink.essentials.internal.helper.DatabaseField;
043: import oracle.toplink.essentials.internal.sessions.ObjectChangeSet;
044: import oracle.toplink.essentials.queryframework.*;
045: import oracle.toplink.essentials.internal.sessions.AbstractRecord;
046: import oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl;
047: import oracle.toplink.essentials.internal.sessions.AbstractSession;
048: import oracle.toplink.essentials.descriptors.ClassDescriptor;
049:
050: public interface OptimisticLockingPolicy extends Cloneable,
051: Serializable {
052:
053: /**
054: * INTERNAL:
055: * Add update fields for template row.
056: * These are any unmapped fields required to write in an update.
057: *
058: * #see this method in VersionLockingPolicy
059: */
060: public void addLockFieldsToUpdateRow(AbstractRecord databaseRow,
061: AbstractSession session);
062:
063: /**
064: * INTERNAL:
065: * The method should update the translation row with the
066: * correct write lock values. This method is called on a delete.
067: *
068: * #see this method in VersionLockingPolicy
069: */
070: public void addLockValuesToTranslationRow(
071: ObjectLevelModifyQuery query);
072:
073: /**
074: * INTERNAL:
075: * When given an expression, this method will return a new expression with
076: * the optimistic locking values included. This expression will be used
077: * in a delete call.
078: *
079: * #see this method in VersionLockingPolicy
080: */
081: public Expression buildDeleteExpression(
082: oracle.toplink.essentials.internal.helper.DatabaseTable table,
083: Expression mainExpression, AbstractRecord row);
084:
085: /**
086: * INTERNAL:
087: * When given an expression, this method will return a new expression with
088: * the optimistic locking values included. This expression will be used in
089: * an update call.
090: *
091: * #see this method in VersionLockingPolicy
092: */
093: public Expression buildUpdateExpression(
094: oracle.toplink.essentials.internal.helper.DatabaseTable table,
095: Expression mainExpression, AbstractRecord translationRow,
096: AbstractRecord modifyRow);
097:
098: public Object clone();
099:
100: /**
101: * INTERNAL:
102: * This method compares two writeLockValues.
103: * The writeLockValues should be non-null and of the correct type.
104: * Returns:
105: * -1 if value1 is less (older) than value2;
106: * 0 if value1 equals value2;
107: * 1 if value1 is greater (newer) than value2.
108: * Throws:
109: * NullPointerException if the passed value is null;
110: * ClassCastException if the passed value is of a wrong type.
111: */
112: public int compareWriteLockValues(Object value1, Object value2);
113:
114: /**
115: * INTERNAL:
116: * This is the base value that is older than all other values, it is used in the place of
117: * null in some situations.
118: */
119: abstract public Object getBaseValue();
120:
121: /**
122: * INTERNAL:
123: * Return the value that should be stored in the identity map.
124: * If the value is not stored in the cache, then return a null.
125: *
126: * #see this method in VersionLockingPolicy
127: */
128: public Object getValueToPutInCache(AbstractRecord row,
129: AbstractSession session);
130:
131: /**
132: * PUBLIC:
133: * Return the number of versions different between these objects.
134: */
135: public int getVersionDifference(Object currentValue,
136: Object domainObject, Vector primaryKeys,
137: AbstractSession session);
138:
139: /**
140: * INTERNAL:
141: * Return the write lock field.
142: *
143: * #see this method in VersionLockingPolicy
144: */
145: public DatabaseField getWriteLockField();
146:
147: /**
148: * INTERNAL:
149: * This method will return the optimistic lock value for the object
150: *
151: * #see this method in VersionLockingPolicy
152: */
153: public Object getWriteLockValue(Object domainObject,
154: java.util.Vector primaryKey, AbstractSession session);
155:
156: /**
157: * INTERNAL:
158: * This method will return an expression that is used to update its optimistic
159: * locking field.
160: *
161: * #see this method in VersionLockingPolicy
162: */
163: public Expression getWriteLockUpdateExpression(
164: ExpressionBuilder builder);
165:
166: /**
167: * INTERNAL:
168: * It is responsible for initializing the policy.
169: *
170: * #see this method in VersionLockingPolicy
171: */
172: public void initialize(AbstractSession session);
173:
174: /**
175: * INTERNAL:
176: * Responsible for pre-initializing.
177: *
178: * #see this method in VersionLockingPolicy
179: */
180: public void initializeProperties();
181:
182: /**
183: * INTERNAL:
184: * Update the parent write lock value if the changeSet's is newer
185: */
186: public boolean isChildWriteLockValueGreater(
187: AbstractSession session, java.util.Vector primaryKey,
188: Class original, ObjectChangeSet changeSet);
189:
190: /**
191: * INTERNAL:
192: * Update the parent write lock value if the unit of works has been incremented
193: */
194: public boolean isChildWriteLockValueGreater(UnitOfWorkImpl uow,
195: java.util.Vector primaryKey, Class original);
196:
197: /**
198: * INTERNAL:
199: * Returns true if the value stored with the domainObject is more recent
200: * than the value . Returns false otherwise.
201: *
202: * #see this method in VersionLockingPolicy
203: */
204: public boolean isNewerVersion(Object currentValue,
205: Object domainObject, java.util.Vector primaryKey,
206: AbstractSession session);
207:
208: /**
209: * INTERNAL:
210: * Returns true if the value stored with the domainObject is more recent
211: * than the value in the row. Returns false otherwise.
212: * NOTE: This method will only be called if the shouldOnlyRefreshCacheIfNewerVersion()
213: * flag is set on descriptor.
214: *
215: * #see this method in VersionLockingPolicy
216: */
217: public boolean isNewerVersion(AbstractRecord databaseRow,
218: Object domainObject, java.util.Vector primaryKey,
219: AbstractSession session);
220:
221: /**
222: * INTERNAL:
223: * This method should merge changes from the parent into the child.
224: *
225: * #see this method in VersionLockingPolicy
226: */
227: public void mergeIntoParentCache(UnitOfWorkImpl uow,
228: java.util.Vector primaryKey, Object object);
229:
230: /**
231: * INTERNAL:
232: * provide a way to set the descriptor for this policy
233: */
234: public void setDescriptor(ClassDescriptor descriptor);
235:
236: /**
237: * INTERNAL:
238: * Add the initial right lock values to the modify
239: * row in the query. This method will only be called
240: * on insert.
241: *
242: * #see this method in VersionLockingPolicy
243: */
244: public void setupWriteFieldsForInsert(ObjectLevelModifyQuery query);
245:
246: /**
247: * INTERNAL:
248: * This method should update the translation row, the modify
249: * row and the domain object with th lock value.
250: *
251: * #see this method in VersionLockingPolicy
252: */
253: public void updateRowAndObjectForUpdate(
254: ObjectLevelModifyQuery query, Object object);
255:
256: public void validateDelete(int rowCount, Object object,
257: WriteObjectQuery query);
258:
259: public void validateUpdate(int rowCount, Object object,
260: WriteObjectQuery query);
261:
262: /**
263: * INTERNAL:
264: * Prepare fetch group for read query
265: */
266: public void prepareFetchGroupForReadQuery(FetchGroup fetchGroup,
267: ObjectLevelReadQuery query);
268: }
|