Transaction


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