[Zodb-checkins] CVS: Zope3/src/zodb/storage - interfaces.py:1.1

[Jeremy Hylton]

Update of /cvs-repository/Zope3/src/zodb/storage
In directory cvs.zope.org:/tmp/cvs-serv21643

Added Files:
	interfaces.py 
Log Message:
Add a set of storage interfaces.

There's still lots more to be done on the interfaces, but at least
it's a start.


=== Added File Zope3/src/zodb/storage/interfaces.py ===
##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""ZODB storage interface

$Id: interfaces.py,v 1.1 2003/02/03 22:54:01 jeremy Exp $
"""

from zope.interface import Interface

class IStorage(Interface):
    """Storage layer for ZODB.

    This part of the interface should document important concepts like
    what methods must execute in a transaction context.
    """

    def close():
        """Close the storage.

        The storage should be in a stable persistent state and any
        external resources should be freed.  After this method is called,
        the storage should not be used.

        It should be possible to call close() more than once.
        """

    def cleanup():
        """Remove all files created by the storage.

        This method primarily exists to support the test suite.
        """

    def sortKey():
        """Return a string representing the transaction sort key.

        Every storage instance must have a sort key that uniquely
        identifies the storage.  The key must be unique across all
        storages participating in a transaction.  It should never
        change.

        If a storage can be used in a distributed setting, then the
        sort key should be unique across all storages available on the
        network.
        """

    def getVersion():
        """Return the database version string for the data in the storage."""

    def setVersion():
        """Set the database version string for the data in the storage."""

    def load(oid, version=""):
        """Return data record and serial number for object `oid`.

        Raises KeyError if the object does not exist.  Note that a
        storage supporting multiple revisions will raise KeyError when
        an object does not currently exist, even though historical
        revisions of the object are still in the database.

        Takes an optional argument that specifies the version to read from.
        """

    def getSerial(oid):
        """Return the current serial number for oid."""

    def store(oid, serial, data, version, txn):
        """Store an object and returns a new serial number.

        Arguments:
        oid -- the object id, a string
        serial -- the serial number of the revision read by txn, a string
        data -- the data record, a string
        version -- the version, a string, typically the empty string
        txn -- the current transaction

        Raises ConflictError if `serial` does not match the serial number
        of the most recent revision of the object.

        Raises VersionLockError if `oid` is locked in a version other
        than `version`.

        Raises StorageTransactionError when `txn` is not the current
        transaction.

        XXX Should the funny return serial number from conflict resolution
        be documented.

        XXX ZEO client storage has a really gross extension to this
        protocol that complicates the return value.  Maybe we can fix that.
        """

    def restore(oid, serial, data, version, prev_txn, txn):
        """Store an object with performing consistency checks.

        The arguments are the same as store() except for prev_txn.
        If prev_txn is not None, then prev_txn is the
        """
        pass

    def new_oid():
        pass

    def registerDB(db):
        pass

    def isReadOnly():
        pass

    def supportsUndo():
        pass

    def supportsVersions():
        pass

    def getExtensionMethods():
        pass

    def copyTransactionsFrom(other, versbose=False):
        pass

    def iterator(start=None, stop=None):
        pass

    def lastTransaction():
        pass

    def lastSerial(oid):
        pass

    # two-phase commit

    def tpc_begin(txn):
        pass

    def tpc_vote(txn):
        pass

    def tpc_finish(txn):
        pass

    def tpc_abort(txn):
        pass

    # storages that keep revisions

    def transactionalUndo(txnid, txn):
        pass

    def undoInfo(first=0, last=-20, specification=None):
        pass

    def undoLog(first, last, filter=None):
        pass

    def pack(t):
        pass

    def getSerial(oid):
        pass

    def loadSerial(oid, serial):
        pass

class IUndoStorage(Interface):
    
    def pack(t):
        pass

    def loadSerial(oid, serial):
        pass
    
    def transactionalUndo(txnid, txn):
        pass

    def undoInfo(first=0, last=-20, specification=None):
        pass

    def undoLog(first, last, filter=None):
        """deprecated, using undoInfo instead"""

class IVersionStorage(Interface):
    # XXX should be renamed
    def abortVersion(version):
        pass

    def commitVersion(version):
        pass

    def modifiedInVersion(oid):
        pass

    def versionEmpty(version):
        pass

    def versions(max=None): 
       pass

class IStorageIterator(Interface):

    def close():
        """Close the iterator and free any external resources."""

    def next():
        """Return the next transaction record iterator.

        Raises IndexError if there are no more.
        """

class ITransactionRecordIterator(Interface):

    tid = Attribute("tid", "transaction id, a string")
    status = Attribute("status", "transaction status, a character")
    user = Attribute("user", "username, if set")
    description = Attribute("description", "description of the transaction")

    # XXX what about this one?
    _extension = Attribute("_extension", "the pickled extensions dictionary")

    def next():
        """Return the next data record.

        Raises IndexError if there are no more.
        """
    
class IDataRecord(Interface):

    oid = Attribute("oid", "object id")
    serial = Attribute("serial", "revision serial number")
    version = Attribute("version", "version string")
    data = Attribute("data", "data record")
    data_txn = Attribute("data_txn",
                         """id of previous transaction or None

                         If previous transaction is not None, then it
                         is the id of the transaction that originally
                         wrote the data.  The current transaction contains
                         a logical copy of that data.
                         """)