001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.Transaction
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw;
023:
024: import org.apache.derby.iapi.services.daemon.Serviceable;
025: import org.apache.derby.iapi.error.StandardException;
026: import org.apache.derby.iapi.store.raw.log.LogInstant;
027: import org.apache.derby.iapi.store.access.FileResource;
028: import org.apache.derby.iapi.store.access.RowSource;
029: import org.apache.derby.iapi.store.access.TransactionController;
030: import org.apache.derby.iapi.services.context.ContextManager;
031:
032: import java.util.Properties;
033:
034: import org.apache.derby.iapi.services.property.PersistentSet;
035:
036: import org.apache.derby.iapi.error.ExceptionSeverity;
037:
038: /**
039: */
040:
041: public interface Transaction {
042:
043: /**
044: Return the context manager this transaction is associated with.
045: */
046: public ContextManager getContextManager();
047:
048: /**
049: * Get the compatibility space of the transaction.
050: * <p>
051: * Returns an object that can be used with the lock manager to provide
052: * the compatibility space of a transaction. 2 transactions with the
053: * same compatibility space will not conflict in locks. The usual case
054: * is that each transaction has it's own unique compatibility space.
055: * <p>
056: *
057: * @return The compatibility space of the transaction.
058: **/
059: Object getCompatibilitySpace();
060:
061: /**
062: Called after the transaction has been attached to an Access Manger
063: TransactionController. Thus may not be called for all transactions.
064: Purpose is to allow a transaction access to database (service) properties.
065:
066: Will not be called for transactions early in the boot process, ie. before
067: the property conglomerate is set up.
068: @exception StandardException Standard cloudscape exception policy
069: */
070: public void setup(PersistentSet set) throws StandardException;
071:
072: /**
073: Return my transaction identifier. Transaction identifiers may be
074: re-used for transactions that do not modify the raw store.
075: May return null if this transaction has no globalId.
076: */
077: public GlobalTransactionId getGlobalId();
078:
079: /**
080: Get the current default locking policy for all operations within this
081: transaction. The transaction is initially started with a default
082: locking policy equivalent to
083: <PRE>
084: newLockingPolicy(
085: LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
086: </PRE>
087: This default can be changed by subsequent calls to
088: setDefaultLockingPolicy(LockingPolicy policy).
089:
090:
091: @return The current default locking policy in this transaction.
092: */
093:
094: public LockingPolicy getDefaultLockingPolicy();
095:
096: /**
097: Obtain a locking policy for use in openContainer(). The mode
098: and isolation must be constants from LockingPolicy. If higherOK is true
099: then the object returned may implement a stricter form of locking than
100: the one requested.
101: <BR>
102: A null LockingPolicy reference is identical to a LockingPolicy obtained
103: by using MODE_NONE which is guaranteed to exist.
104:
105: @param mode A constant of the form LockingPolicy.MODE_*
106: @param isolation A constant of the form LockingPolicy.ISOLATION_*
107: @param stricterOk True if a stricter level of locking is acceptable,
108: false if an exact match is required.
109:
110: @return A object that can be used in an openContainer call,
111: null if a matching policy cannot be found.
112: */
113:
114: public LockingPolicy newLockingPolicy(int mode, int isolation,
115: boolean stricterOk);
116:
117: /**
118: Set the default locking policy for all operations within this
119: transaction. The transaction is intially started with a default
120: locking policy equivalent to
121: <PRE>
122: newLockingPolicy(
123: LockingPolicy.MODE_RECORD, LockingPolicy.ISOLATION_SERIALIZABLE, true);
124: </PRE>
125:
126: @param policy The lock policy to use, if null then then a no locking
127: policy will be installed as the default.
128: */
129:
130: public void setDefaultLockingPolicy(LockingPolicy policy);
131:
132: /**
133: Commit this transaction. All savepoints within this transaction are
134: released.
135:
136: @return the commit instant of this transaction, or null if it
137: didn't make any changes
138:
139: @exception StandardException
140: A transaction level exception is thrown
141: if the transaction was aborted due to some error. Any exceptions that
142: occur of lower severity than Transaction severity are caught, the
143: transaction is then aborted and then an exception of Transaction
144: severity is thrown nesting the original exception.
145:
146: @exception StandardException Any exception more severe than a
147: Transaction exception is not caught and the transaction is not aborted.
148: The transaction will be aborted by the standard context mechanism.
149:
150: */
151:
152: public LogInstant commit() throws StandardException;
153:
154: /**
155: "Commit" this transaction without sync'ing the log.
156: Everything else is identical to commit(), use this at your own risk.
157:
158: <BR>bits in the commitflag can turn on to fine tuned the "commit":
159: KEEP_LOCKS - no locks will be released by the commit and no post commit
160: processing will be initiated. If, for some reasons, the locks cannot be
161: kept even if this flag is set, then the commit will sync the log, i.e.,
162: it will revert to the normal commit.
163:
164: @exception StandardException
165: A transaction level exception is thrown
166: if the transaction was aborted due to some error. Any exceptions that
167: occur of lower severity than Transaction severity are caught, the
168: transaction is then aborted and then an exception of Transaction
169: severity is thrown nesting the original exception.
170:
171: @exception StandardException Any exception more severe than a
172: Transaction exception is not caught and the transaction is not aborted.
173: The transaction will be aborted by the standard context mechanism.
174: */
175:
176: public LogInstant commitNoSync(int commitflag)
177: throws StandardException;
178:
179: public final int RELEASE_LOCKS = TransactionController.RELEASE_LOCKS;
180: public final int KEEP_LOCKS = TransactionController.KEEP_LOCKS;
181:
182: /**
183: Abort all changes made by this transaction since the last commit, abort
184: or the point the transaction was started, whichever is the most recent.
185: All savepoints within this transaction are released.
186:
187: @exception StandardException Only exceptions with severities greater
188: than ExceptionSeverity.TRANSACTION_SEVERITY will be thrown.
189:
190: */
191: public void abort() throws StandardException;
192:
193: /**
194: Close this transaction, the transaction must be idle. This close will
195: pop the transaction context off the stack that was pushed when the
196: transaction was started.
197:
198: @see RawStoreFactory#startTransaction
199:
200: @exception StandardException Standard Cloudscape error policy
201: @exception StandardException A transaction level exception is
202: thrown if the transaction is not idle.
203:
204:
205: */
206: public void close() throws StandardException;
207:
208: /**
209: If this transaction is not idle, abort it. After this call close().
210:
211: @see RawStoreFactory#startTransaction
212:
213: @exception StandardException Standard Cloudscape error policy
214: @exception StandardException A transaction level exception is
215: thrown if the transaction is not idle.
216:
217:
218: */
219: public void destroy() throws StandardException;
220:
221: /**
222: Set a save point in the current transaction. A save point defines a
223: point in time in the transaction that changes can be rolled back to.
224: Savepoints can be nested and they behave like a stack. Setting save
225: points "one" and "two" and the rolling back "one" will rollback all
226: the changes made since "one" (including those made since "two") and
227: release savepoint "two".
228: @param name The user provided name of the savepoint
229: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
230: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
231: A String value for kindOfSavepoint would mean it is SQL savepoint
232: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
233:
234: @return returns total number of savepoints in the stack.
235: @exception StandardException Standard cloudscape exception policy
236: @exception StandardException
237: A statement level exception is thrown if a savepoint already
238: exists in the current transaction with the same name.
239:
240: */
241:
242: public int setSavePoint(String name, Object kindOfSavepoint)
243: throws StandardException;
244:
245: /**
246: Release the save point of the given name. Relasing a savepoint removes
247: all knowledge from this transaction of the named savepoint and any
248: savepoints set since the named savepoint was set.
249: @param name The user provided name of the savepoint, set by the user
250: in the setSavePoint() call.
251: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
252: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
253: A String value for kindOfSavepoint would mean it is SQL savepoint
254: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
255:
256: @return returns total number of savepoints in the stack.
257: @exception StandardException Standard cloudscape exception policy
258: @exception StandardException
259: A statement level exception is thrown if a savepoint already
260: exists in the current transaction with the same name.
261:
262: */
263:
264: public int releaseSavePoint(String name, Object kindOfSavepoint)
265: throws StandardException;
266:
267: /**
268: Rollback all changes made since the named savepoint was set. The named
269: savepoint is not released, it remains valid within this transaction, and
270: thus can be named it future rollbackToSavePoint() calls. Any savepoints
271: set since this named savepoint are released (and their changes rolled
272: back).
273: @param name The user provided name of the savepoint, set by the user
274: in the setSavePoint() call.
275: @param kindOfSavepoint A NULL value means it is an internal savepoint (ie not a user defined savepoint)
276: Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepoint
277: A String value for kindOfSavepoint would mean it is SQL savepoint
278: A JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint
279:
280: @return returns total number of savepoints in the stack.
281: @exception StandardException Standard cloudscape exception policy
282: @exception StandardException
283: A statement level exception is thrown if no savepoint exists with
284: the given name.
285:
286: */
287: public int rollbackToSavePoint(String name, Object kindOfSavepoint)
288: throws StandardException;
289:
290: /**
291:
292: Open a container, with the transaction's default locking policy.
293:
294: <p>
295: Note that if NOWAIT has been specified lock will be
296: requested with no wait time, and if lock is not granted a
297: SQLState.LOCK_TIMEOUT exception will be thrown.
298: <P>
299: The release() method of ContainerHandle will be called when this
300: transaction is aborted or commited, it may be called explicitly to
301: release the ContainerHandle before the end of the transaction.
302:
303:
304: @return a valid ContainerHandle or null if the container does not exist.
305:
306: @exception StandardException Standard cloudscape exception policy
307:
308: */
309: public ContainerHandle openContainer(ContainerKey containerId,
310: int mode) throws StandardException;
311:
312: /**
313:
314: Open a container, with the defined locking policy, otherwise
315: as openContainer(int containerId, boolean forUpdate).
316:
317: <P>
318: Calls locking.lockContainer(this, returnValue, forUpdate) to lock the
319: container. Note that if NOWAIT has been specified lock will be
320: requested with no wait time, and if lock is not granted a
321: SQLState.LOCK_TIMEOUT exception will be thrown.
322:
323: @param locking The lock policy to use, if null then then a no locking
324: policy will be used.
325:
326: @return a valid ContainerHandle or null if the container does not exist.
327:
328: @exception StandardException Standard cloudscape exception policy
329:
330: */
331:
332: public ContainerHandle openContainer(ContainerKey containerId,
333: LockingPolicy locking, int mode) throws StandardException;
334:
335: /**
336: Add a new container to the segment. The new container initially has
337: one page, page Container.FIRST_PAGE_NUMBER.
338:
339: <BR>
340: If pageSize is equal to ContainerHandle.DEFAULT_PAGESIZE or invalid
341: then a default page size will be picked.
342: <BR>
343: SpareSpace indicates that percent (0% - 100%) of page space that will
344: be attempted to be reserved for updates. E.g. with a value of 20 a page
345: that would normally hold 40 rows will be limited to 32 rows,
346: actual calculation for the threshold where no more inserts are all
347: accepted is up to the implementation. Whatever the value of
348: spaceSpace an empty page will always accept at least one insert.
349: If spare space is equal to ContainerHandle.DEFAULT_PAGESIZE or invalid
350: then a default value will be used.
351:
352: <P><B>Synchronisation</B>
353: <P>
354: The new container is exclusivly locked by this transaction until
355: it commits.
356:
357: @param segmentId segment to create the container in.
358: @param containerId If not equal to 0 then this container id will be
359: used to create the container, else if set to 0 then
360: the raw store will assign a number.
361: @param mode mode description in @see ContainerHandle. This mode is
362: only effective for the duration of the addContainer call and not stored
363: persistently for the lifetime of the container.
364: @param tableProperties Implementation-specific properties of the
365: conglomerate.
366:
367: @return a container identifer that can be used in openContainer()
368: This id is only valid within this RawStoreFactory. Returns a negative
369: number if a container could not be allocated.
370:
371: @exception StandardException Standard Cloudscape error policy
372:
373: */
374: public long addContainer(long segmentId, long containerId,
375: int mode, Properties tableProperties, int temporaryFlag)
376: throws StandardException;
377:
378: /**
379: Drop a container.
380:
381: <P><B>Synchronisation</B>
382: <P>
383: This call will mark the container as dropped and then obtain an CX lock
384: on the container. Once a container has been marked as dropped it cannot
385: be retrieved by any openContainer() call.
386: <P>
387: Once the exclusive lock has been obtained the container is removed
388: and all its pages deallocated. The container will be fully removed
389: at the commit time of the transaction.
390:
391: @exception StandardException Standard Cloudscape error policy
392:
393: */
394: public void dropContainer(ContainerKey containerId)
395: throws StandardException;
396:
397: /**
398: Add a new stream container to the segment and load the stream container.
399:
400: This stream container doesn't not have locks, and do not log.
401: It does not have the concept of a page.
402: It is used by the external sort only.
403:
404: <P><B>Synchronisation</B>
405: <P>
406: This call will mark the container as dropped and then obtain an CX lock
407: on the container. Once a container has been marked as dropped it cannot
408: be retrieved by any openContainer() call.
409: <P>
410: Once the exclusive lock has been obtained the container is removed
411: and all its pages deallocated. The container will be fully removed
412: at the commit time of the transaction.
413:
414: @exception StandardException Standard Cloudscape error policy
415:
416: */
417: public long addAndLoadStreamContainer(long segmentId,
418: Properties tableProperties, RowSource rowSource)
419: throws StandardException;
420:
421: /**
422: Open a stream container.
423:
424: @return a valid StreamContainerHandle or null if the container does not exist.
425:
426: @exception StandardException Standard cloudscape exception policy
427:
428: */
429: public StreamContainerHandle openStreamContainer(long segmentId,
430: long containerId, boolean hold) throws StandardException;
431:
432: /**
433: Drop a stream container.
434:
435: <P><B>Synchronisation</B>
436: <P>
437: This call will remove the container.
438:
439: @exception StandardException Standard Cloudscape error policy
440:
441: */
442: public abstract void dropStreamContainer(long segmentId,
443: long containerId) throws StandardException;
444:
445: /**
446: Log an operation and then action it in the context of this transaction.
447: The Loggable Operation is logged in the transaction log file and then
448: its doMe method is called to perform the required change. If this
449: transaction aborts or a rollback is performed of the current savepoint
450: (if any) then a compensation Operation needs to be generated that will
451: compensate for the change of this Operation.
452:
453: @param operation the operation that is to be applied
454:
455: @see Loggable
456:
457: @exception StandardException Standard cloudscape exception policy
458:
459: */
460: public void logAndDo(Loggable operation) throws StandardException;
461:
462: /**
463: Add to the list of post commit work that may be processed after this
464: transaction commits. If this transaction aborts, then the post commit
465: work list will be thrown away. No post commit work will be taken out
466: on a rollback to save point.
467:
468: @param work the post commit work that is added
469: */
470: public void addPostCommitWork(Serviceable work);
471:
472: /**
473: Add to the list of post termination work that may be processed after this
474: transaction commits or aborts.
475:
476: @param work the post termination work that is added
477: */
478: public void addPostTerminationWork(Serviceable work);
479:
480: /**
481: * Reveals whether the transaction has ever read or written data.
482: *
483: * @return true If the transaction has never read or written data.
484: **/
485: public boolean isIdle();
486:
487: /**
488: Reveal whether the transaction is in a pristine state, which
489: means it hasn't done any updates since the last commit.
490: @return true if so, false otherwise
491: */
492: public boolean isPristine();
493:
494: /**
495: Get an object to handle non-transactional files.
496: */
497: public FileResource getFileHandler();
498:
499: /**
500: Get cache statistics for the specified cache
501: */
502: public abstract long[] getCacheStats(String cacheName);
503:
504: /**
505: Reset the cache statistics for the specified cache
506: */
507: public abstract void resetCacheStats(String cacheName);
508:
509: /**
510: Return true if any transaction is blocked, even if not by this one.
511: */
512: public boolean anyoneBlocked();
513:
514: /**
515: * Convert a local transaction to a global transaction.
516: * <p>
517: * Get a transaction controller with which to manipulate data within
518: * the access manager. Tbis controller allows one to manipulate a
519: * global XA conforming transaction.
520: * <p>
521: * Must only be called a previous local transaction was created and exists
522: * in the context. Can only be called if the current transaction is in
523: * the idle state.
524: * <p>
525: * The (format_id, global_id, branch_id) triplet is meant to come exactly
526: * from a javax.transaction.xa.Xid. We don't use Xid so that the system
527: * can be delivered on a non-1.2 vm system and not require the javax classes
528: * in the path.
529: *
530: * @param format_id the format id part of the Xid - ie. Xid.getFormatId().
531: * @param global_id the global transaction identifier part of XID - ie.
532: * Xid.getGlobalTransactionId().
533: * @param branch_id The branch qualifier of the Xid - ie.
534: * Xid.getBranchQaulifier()
535: *
536: * @exception StandardException Standard exception policy.
537: **/
538: void createXATransactionFromLocalTransaction(int format_id,
539: byte[] global_id, byte[] branch_id)
540: throws StandardException;
541:
542: /**
543: * This method is called to commit the current XA global transaction.
544: * <p>
545: * RESOLVE - how do we map to the "right" XAExceptions.
546: * <p>
547: *
548: *
549: * @param onePhase If true, the resource manager should use a one-phase
550: * commit protocol to commit the work done on behalf of
551: * current xid.
552: *
553: * @exception StandardException Standard exception policy.
554: **/
555: public void xa_commit(boolean onePhase) throws StandardException;
556:
557: /**
558: * This method is called to ask the resource manager to prepare for
559: * a transaction commit of the transaction specified in xid.
560: * <p>
561: *
562: * @return A value indicating the resource manager's vote on the
563: * the outcome of the transaction. The possible values
564: * are: XA_RDONLY or XA_OK. If the resource manager wants
565: * to roll back the transaction, it should do so by
566: * throwing an appropriate XAException in the prepare
567: * method.
568: *
569: * @exception StandardException Standard exception policy.
570: **/
571: public int xa_prepare() throws StandardException;
572:
573: public static final int XA_RDONLY = 1;
574: public static final int XA_OK = 2;
575:
576: /**
577: * rollback the current global transaction.
578: * <p>
579: * The given transaction is roll'ed back and it's history is not
580: * maintained in the transaction table or long term log.
581: * <p>
582: *
583: * @exception StandardException Standard exception policy.
584: **/
585: public void xa_rollback() throws StandardException;
586:
587: /**
588: * get string ID of the actual transaction ID that will
589: * be used when transaction is in active state.
590: */
591: public String getActiveStateTxIdString();
592:
593: }
|