m Ec@sdZdkZdeiifdYZdeiifdYZdeiifdYZdeiifd YZd efd YZ d eiifd YZ deiifdYZ de fdYZ deiifdYZdS(sQTransaction Interfaces $Id: interfaces.py 41164 2006-01-05 21:12:02Z anguenot $ NtITransactionManagercBsPtZdZdZdZdZdZedZdZ dZ RS(sAn object that manages a sequence of transactions. Applications use transaction managers to establish transaction boundaries. cCsdS(sBegin a new transaction. If an existing transaction is in progress, it will be aborted. The newTransaction() method of registered synchronizers is called, passing the new transaction object. N((((t5/data/zmath/zope/lib/python/transaction/interfaces.pytbeginscCsdS(s%Get the current transaction. N((((Rtget$scCsdS(s(Commit the current transaction. N((((Rtcommit(scCsdS(s'Abort the current transaction. N((((Rtabort,scCsdS(sCreate a savepoint from the current transaction. If the optimistic argument is true, then data managers that don't support savepoints can be used, but an error will be raised if the savepoint is rolled back. An ISavepoint object is returned. N((t optimistic((Rt savepoint0scCsdS(sRegister an ISynchronizer. Synchronizers are notified about some major events in a transaction's life. See ISynchronizer for details. N((tsynch((Rt registerSynch:scCsdS(sUnregister an ISynchronizer. Synchronizers are notified about some major events in a transaction's life. See ISynchronizer for details. N((R((RtunregisterSynchAs( t__name__t __module__t__doc__RRRRtFalseRR R (((RRs     t ITransactioncBstZdZeiidZeiidZdZdZ e dZ dZ dZ dd Zd Zd Zfed Zd ZfedZdZRS(s&Object representing a running transaction. Objects with this interface may represent different transactions during their lifetime (.begin() can be called to start a new transaction using the same instance, although that example is deprecated and will go away in ZODB 3.6). sA user name associated with the transaction. The format of the user name is defined by the application. The value is of Python type str. Storages record the user value, as meta-data, when a transaction commits. A storage may impose a limit on the size of the value; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or truncate the value). sA textual description of the transaction. The value is of Python type str. Method note() is the intended way to set the value. Storages record the description, as meta-data, when a transaction commits. A storage may impose a limit on the size of the description; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or truncate the value). cCsdS(sFinalize the transaction. This executes the two-phase commit algorithm for all IDataManager objects associated with the transaction. N((((RRiscCsdS(sAbort the transaction. This is called from the application. This can only be called before the two-phase commit protocol has been started. N((((RRpscCsdS(sCreate a savepoint. If the optimistic argument is true, then data managers that don't support savepoints can be used, but an error will be raised if the savepoint is rolled back. An ISavepoint object is returned. N((R((RRwscCsdS(sAdd a data manager to the transaction. `datamanager` must provide the transactions.interfaces.IDataManager interface. N((t datamanager((RtjoinscCsdS(s~Add text to the transaction description. This modifies the `.description` attribute; see its docs for more detail. First surrounding whitespace is stripped from `text`. If `.description` is currently an empty string, then the stripped text becomes its value, else two newlines and the stripped text are appended to `.description`. N((ttext((Rtnotest/cCsdS(s2Set the user name. path should be provided if needed to further qualify the identified user. This is a convenience method used by Zope. It sets the .user attribute to str(path) + " " + str(user_name). This sets the `.user` attribute; see its docs for more detail. N((t user_nametpath((RtsetUserscCsdS(sCAdd extension data to the transaction. name is the name of the extension property to set, of Python type str; value must be picklable. Multiple calls may be made to set multiple extension properties, provided the names are distinct. Storages record the extension data, as meta-data, when a transaction commits. A storage may impose a limit on the size of extension data; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or remove `` pairs). N((tnametvalue((RtsetExtendedInfos cOsdS(sNRegister a hook to call before the transaction is committed. THIS IS DEPRECATED IN ZODB 3.6. Use addBeforeCommitHook() instead. The specified hook function will be called after the transaction's commit method has been called, but before the commit process has been started. The hook will be passed the specified positional and keyword arguments. Multiple hooks can be registered and will be called in the order they were registered (first registered, first called). This method can also be called from a hook: an executing hook can register more hooks. Applications should take care to avoid creating infinite loops by recursively registering hooks. Hooks are called only for a top-level commit. A subtransaction commit does not call any hooks. If the transaction is aborted, hooks are not called, and are discarded. Calling a hook "consumes" its registration too: hook registrations do not persist across transactions. If it's desired to call the same hook on every transaction commit, then beforeCommitHook() must be called with that hook during every transaction; in such a case consider registering a synchronizer object via a TransactionManager's registerSynch() method instead. N((t_ITransaction__hooktargstkws((RtbeforeCommitHookscCsdS(sJRegister a hook to call before the transaction is committed. The specified hook function will be called after the transaction's commit method has been called, but before the commit process has been started. The hook will be passed the specified positional (`args`) and keyword (`kws`) arguments. `args` is a sequence of positional arguments to be passed, defaulting to an empty tuple (no positional arguments are passed). `kws` is a dictionary of keyword argument names and values to be passed, or the default None (no keyword arguments are passed). Multiple hooks can be registered and will be called in the order they were registered (first registered, first called). This method can also be called from a hook: an executing hook can register more hooks. Applications should take care to avoid creating infinite loops by recursively registering hooks. Hooks are called only for a top-level commit. A subtransaction commit or savepoint creation does not call any hooks. If the transaction is aborted, hooks are not called, and are discarded. Calling a hook "consumes" its registration too: hook registrations do not persist across transactions. If it's desired to call the same hook on every transaction commit, then addBeforeCommitHook() must be called with that hook during every transaction; in such a case consider registering a synchronizer object via a TransactionManager's registerSynch() method instead. N((thookRR((RtaddBeforeCommitHookscCsdS(sReturn iterable producing the registered addBeforeCommit hooks. A triple (hook, args, kws) is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction commit. N((((RtgetBeforeCommitHooksscCsdS(s~Register a hook to call after a transaction commit attempt. The specified hook function will be called after the transaction commit succeeds or aborts. The first argument passed to the hook is a Boolean value, true if the commit succeeded, or false if the commit aborted. `args` specifies additional positional, and `kws` keyword, arguments to pass to the hook. `args` is a sequence of positional arguments to be passed, defaulting to an empty tuple (only the true/false success argument is passed). `kws` is a dictionary of keyword argument names and values to be passed, or the default None (no keyword arguments are passed). Multiple hooks can be registered and will be called in the order they were registered (first registered, first called). This method can also be called from a hook: an executing hook can register more hooks. Applications should take care to avoid creating infinite loops by recursively registering hooks. Hooks are called only for a top-level commit. A subtransaction commit or savepoint creation does not call any hooks. Calling a hook "consumes" its registration: hook registrations do not persist across transactions. If it's desired to call the same hook on every transaction commit, then addAfterCommitHook() must be called with that hook during every transaction; in such a case consider registering a synchronizer object via a TransactionManager's registerSynch() method instead. N((RRR((RtaddAfterCommitHookscCsdS(sReturn iterable producing the registered addAfterCommit hooks. A triple (hook, args, kws) is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction commit. N((((RtgetAfterCommitHookss(R R R tzopet interfacet Attributetusert descriptionRRRRRRRRRtNoneR R!R"R#(((RRHs        tITransactionDeprecatedcBs#tZdZedZdZRS(s(Deprecated parts of the transaction API.cCsdS(sBegin a new transaction. If the transaction is in progress, it is aborted and a new transaction is started using the same transaction object. N((tinfo((RRscCsdS(s2Register the given object for transaction control.N((tobject((Rtregisters(R R R R)RR-(((RR*s  t IDataManagercBs_tZdZeiidZdZdZdZ dZ dZ dZ dZ RS( sObjects that manage transactional storage. These objects may manage data for other objects, or they may manage non-object storages, such as relational databases. For example, a ZODB.Connection. Note that when some data is modified, that data's data manager should join a transaction so that data can be committed when the user commits the transaction. sThe transaction manager (TM) used by this data manager. This is a public attribute, intended for read-only use. The value is an instance of ITransactionManager, typically set by the data manager's constructor. cCsdS(sAbort a transaction and forget all changes. Abort must be called outside of a two-phase commit. Abort is called by the transaction manager to abort transactions that are not yet in a two-phase commit. N((t transaction((RR3scCsdS(sBegin commit of a transaction, starting the two-phase commit. transaction is the ITransaction instance associated with the transaction being committed. N((R/((Rt tpc_beginAscCsdS(sCommit modifications to registered objects. Save changes to be made persistent if the transaction commits (if tpc_finish is called later). If tpc_abort is called later, changes must not persist. This includes conflict detection and handling. If no conflicts or errors occur, the data manager should be prepared to make the changes persist when tpc_finish is called. N((R/((RRHs cCsdS(s(Verify that a data manager can commit the transaction. This is the last chance for a data manager to vote 'no'. A data manager votes 'no' by raising an exception. transaction is the ITransaction instance associated with the transaction being committed. N((R/((Rttpc_voteTscCsdS(sIndicate confirmation that the transaction is done. Make all changes to objects modified by this transaction persist. transaction is the ITransaction instance associated with the transaction being committed. This should never fail. If this raises an exception, the database is not expected to maintain consistency; it's a serious error. N((R/((Rt tpc_finish^s cCsdS(sWAbort a transaction. This is called by a transaction manager to end a two-phase commit on the data manager. Abandon all changes to objects modified by this transaction. transaction is the ITransaction instance associated with the transaction being committed. This should never fail. N((R/((Rt tpc_abortks cCsdS(sDReturn a key to use for ordering registered DataManagers. ZODB uses a global sort order to prevent deadlock when it commits transactions involving multiple resource managers. The resource manager must define a sortKey() method that provides a global ordering for resource managers. N((((RtsortKeyxs(R R R R$R%R&ttransaction_managerRR0RR1R2R3R4(((RR.s    tISavepointDataManagercBstZdZRS(NcCsdS(sAReturn a data-manager savepoint (IDataManagerSavepoint). N((((RRs(R R R(((RR6stIDataManagerSavepointcBstZdZdZRS(s#Savepoint for data-manager changes for use in transaction savepoints. Datamanager savepoints are used by, and only by, transaction savepoints. Note that data manager savepoints don't have any notion of, or responsibility for, validity. It isn't the responsibility of data-manager savepoints to prevent multiple rollbacks or rollbacks after transaction termination. Preventing invalid savepoint rollback is the responsibility of transaction rollbacks. Application code should never use data-manager savepoints. cCsdS(s4Rollback any work done since the savepoint. N((((Rtrollbacks(R R R R8(((RR7s t ISavepointcBs)tZdZdZeiidZRS(sA transaction savepoint. cCsdS(sRollback any work done since the savepoint. InvalidSavepointRollbackError is raised if the savepoint isn't valid. N((((RR8ss1Boolean indicating whether the savepoint is valid(R R R R8R$R%R&tvalid(((RR9s  tInvalidSavepointRollbackErrorcBstZdZRS(sAttempt to rollback an invalid savepoint. A savepoint may be invalid because: - The surrounding transaction has committed or aborted. - An earlier savepoint in the same transaction has been rolled back. (R R R (((RR;s t ISynchronizercBs)tZdZdZdZdZRS(sKObjects that participate in the transaction-boundary notification API. cCsdS(sIHook that is called by the transaction at the start of a commit. N((R/((RtbeforeCompletionscCsdS(sJHook that is called by the transaction after completing a commit. N((R/((RtafterCompletionscCsdS(sHook that is called at the start of a transaction. This hook is called when, and only when, a transaction manager's begin() method is called explictly. N((R/((RtnewTransactions(R R R R=R>R?(((RR<s   (R tzope.interfaceR$R%t InterfaceRRR*R.R6R7R9t ExceptionR;R<( R6R9RRR7R*R;R<R$R.((Rt?s 3i