diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index 2e378c92c..614232755 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -432,6 +432,25 @@ def close(): should also close all the Connections. """ +class IStorageTransactionMetaData(Interface): + """Provide storage transaction meta data. + + Note that unlike transaction.interfaces.ITransaction, the ``user`` + and ``description`` attributes are bytes, not text. + """ + user = Attribute("Transaction user") + description = Attribute("Transaction Description") + extension = Attribute( + "A dictionary carrying a transaction's extended_info data") + +class IStorageTransactionMetaDataExtensionBytes(IStorageTransactionMetaData): + """Provide storage transaction meta data. + + Note that unlike transaction.interfaces.ITransaction, the ``user`` + and ``description`` attributes are bytes, not text. + """ + extension_bytes = Attribute( + "A bytes carrying a transaction's serialized extended_info data") class IStorage(Interface): """A storage is responsible for storing and retrieving data of objects. @@ -513,11 +532,11 @@ def history(oid, size=1): An alias for tid, which expected by older clients. user_name - The user identifier, if any (or an empty string) of the + The bytes user identifier, if any (or an empty string) of the user on whos behalf the revision was committed. description - The transaction description for the transaction that + The bytes transaction description for the transaction that committed the revision. size @@ -652,8 +671,7 @@ def store(oid, serial, data, version, transaction): This must be an empty string. It exists for backward compatibility. transaction - A transaction object. This should match the current - transaction for the storage, set by tpc_begin. + The object passed to tpc_begin Several different exceptions may be raised when an error occurs. @@ -675,6 +693,8 @@ def store(oid, serial, data, version, transaction): def tpc_abort(transaction): """Abort the transaction. + The argument is the same object passed to tpc_begin. + Any changes made by the transaction are discarded. This call is ignored is the storage is not participating in @@ -685,6 +705,8 @@ def tpc_abort(transaction): def tpc_begin(transaction): """Begin the two-phase commit process. + The argument provides IStorageTransactionMetaDataExtensionBytes. + If storage is already participating in a two-phase commit using the same transaction, a StorageTransactionError is raised. @@ -703,6 +725,8 @@ def tpc_finish(transaction, func = lambda tid: None): a different transaction. Failure of this method is extremely serious. + The first argument is the same object passed to tpc_begin. + The second argument is a call-back function that must be called while the storage transaction lock is held. It takes the new transaction id generated by the transaction. @@ -714,6 +738,8 @@ def tpc_finish(transaction, func = lambda tid: None): def tpc_vote(transaction): """Provide a storage with an opportunity to veto a transaction + The argument is the same object passed to tpc_begin. + This call raises a StorageTransactionError if the storage isn't participating in two-phase commit or if it is commiting a different transaction. @@ -790,6 +816,8 @@ def tpc_begin(transaction, tid=None): using a different transaction, the call blocks until the current transaction ends (commits or aborts). + The first argument provides IStorageTransactionMetaDataExtensionBytes. + If a transaction id is given, then the transaction will use the given id rather than generating a new id. This is used when copying already committed transactions from another @@ -841,22 +869,22 @@ class IStorageRecordInformation(Interface): """Provide information about a single storage record """ - oid = Attribute("The object id") - tid = Attribute("The transaction id") - data = Attribute("The data record") - version = Attribute("The version id") - data_txn = Attribute("The previous transaction id") - + oid = Attribute("The object id, bytes") + tid = Attribute("The transaction id, bytes") + data = Attribute("The data record, bytes") + data_txn = Attribute("The previous transaction id, bytes") -class IStorageTransactionInformation(Interface): +class IStorageTransactionInformation(IStorageTransactionMetaData): """Provide information about a storage transaction. Can be iterated over to retrieve the records modified in the transaction. + Note that this may contain a status field used by FileStorage to + support packing. At some point, this will go away when FileStorage + has a better pack algoritm. """ tid = Attribute("Transaction id") - status = Attribute("Transaction Status") # XXX what are valid values? user = Attribute("Transaction user") description = Attribute("Transaction Description") extension = Attribute( @@ -888,7 +916,6 @@ def iterator(start=None, stop=None): """ - class IStorageUndoable(IStorage): """A storage supporting transactional undo. """ @@ -923,10 +950,10 @@ def undoLog(first, last, filter=None): "time": The time, as float seconds since the epoch, when the transaction committed. "user_name": The value of the `.user` attribute on that - transaction. + transaction, **bytes**. "description": The value of the `.description` attribute on - that transaction. - "id`" A string uniquely identifying the transaction to the + that transaction, **bytes**. + "id`" A bytes uniquely identifying the transaction to the storage. If it's desired to undo this transaction, this is the `transaction_id` to pass to `undo()`.