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