Commit d39d53d5 authored by Jim Fulton's avatar Jim Fulton

Update the interfaces to be clear that, at the storage level, we're dealing with bytes.

parent 807ba63c
......@@ -432,6 +432,25 @@ class IDatabase(IStorageDB):
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 @@ class IStorage(Interface):
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 @@ class IStorage(Interface):
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 @@ class IStorage(Interface):
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 @@ class IStorage(Interface):
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 @@ class IStorage(Interface):
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 @@ class IStorage(Interface):
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 @@ class IStorageRestoreable(IStorage):
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 @@ class IStorageIteration(Interface):
"""
class IStorageUndoable(IStorage):
"""A storage supporting transactional undo.
"""
......@@ -923,10 +950,10 @@ class IStorageUndoable(IStorage):
"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()`.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment