[Zope-CVS] CVS: Products/AdaptableStorage/serial/interfaces - .cvsignore:1.1 IAspectSerializer.py:1.1 IClassifier.py:1.1 IDeserializationEvent.py:1.1 IDomainMapper.py:1.1 IEventBase.py:1.1 IFullDeserializationEvent.py:1.1 IFullSerializationEvent.py:1.1 IGateway.py:1.1 IKeyedObjectSystem.py:1.1 IObjectGateway.py:1.1 IObjectMapper.py:1.1 IObjectSerializer.py:1.1 ISchema.py:1.1 ISerializationEvent.py:1.1 __init__.py:1.1 public.py:1.1

Shane Hathaway shane@zope.com
Wed, 27 Nov 2002 13:37:09 -0500


Update of /cvs-repository/Products/AdaptableStorage/serial/interfaces
In directory cvs.zope.org:/tmp/cvs-serv12157/serial/interfaces

Added Files:
	.cvsignore IAspectSerializer.py IClassifier.py 
	IDeserializationEvent.py IDomainMapper.py IEventBase.py 
	IFullDeserializationEvent.py IFullSerializationEvent.py 
	IGateway.py IKeyedObjectSystem.py IObjectGateway.py 
	IObjectMapper.py IObjectSerializer.py ISchema.py 
	ISerializationEvent.py __init__.py public.py 
Log Message:
Moved the latest AdaptableStorage work out of the private repository.
It took a long time, but I moved it as soon as all the unit tests
passed and I felt that all the interface names and conventions were
good enough.

Documentation is still minimal, but now I think the system is finally
straight enough in my head to write down. :-) If you want a sneak
peek, the interfaces have some docstrings, if you're looking for a
"tree" view, while the OpenOffice diagram presents something of a
"forest" view.

Also note that I'm trying a new coding convention.  The "public"
module in each package defines exactly which objects should be
exported from the package.  This solves a few problems with imports
such as doubling of names and shadowing of modules.  Overall, the
"public" module makes it easier to tell which classes are supposed to
be used by other packages, and makes it easier for other packages to
use the public classes.  See what you think.



=== Added File Products/AdaptableStorage/serial/interfaces/.cvsignore ===
*.pyc


=== Added File Products/AdaptableStorage/serial/interfaces/IAspectSerializer.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Serialization / deserialization interfaces.

$Id: IAspectSerializer.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface

class IAspectSerializer(Interface):
    """Object aspect serializer / deserializer"""

    def getSchema():
        """Returns the schema of records (de)serialized by this aspect.
        """

    def serialize(object, event):
        """Returns the state of this aspect of the object.

        Use the ISerializationEvent to set up internal and external
        references.
        """

    def deserialize(object, event, state):
        """Fills in the state of this aspect of the object.

        Use the IDeserializationEvent to resolve external references.
        Returns nothing.
        """



=== Added File Products/AdaptableStorage/serial/interfaces/IClassifier.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Classifier interface.

$Id: IClassifier.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface

class IClassifier(Interface):
    """Object classifier

    Implementations of this interface are a little like biologists.
    During serialization, the classifyObject() method returns a
    mapping containing the classification of subob (like a biologist
    identifying a creature's genus and species).  During deserialization, the
    chooseMapper() method decides what kind of objects to use for a
    classification (like a biologist showing you a creature of a certain
    genus and species).

    The keys in the classification are implementation-dependent.
    """

    def classifyObject(value):
        """Returns a classification and mapper_name for the given object.
        """

    def classifyFilename(filename, isdir):
        """Returns a classification and mapper_name given a filename.

        Generally, the filename extension is examined.
        """

    def chooseMapper(classification):
        """Returns a mapper_name given a classification.
        """


=== Added File Products/AdaptableStorage/serial/interfaces/IDeserializationEvent.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Deserialization event interface.

$Id: IDeserializationEvent.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from IEventBase import IEventBase


class IDeserializationEvent(IEventBase):
    """Aspect deserializers call methods of this interface to restore
    internal and external references.
    """

    def notifyDeserialized(name, value):
        """Indicates that a named internal subobject was deserialized.
        """

    def dereference(name, mapper_name=None, key=None, classification=None):
        """Retrieves a referenced subobject (usually ghosted initially).
        """



=== Added File Products/AdaptableStorage/serial/interfaces/IDomainMapper.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Domain mapper interface

$Id: IDomainMapper.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface


class IDomainMapper (Interface):
    """Provides a series of mappers for objects in a domain.
    """

    def getClassifier():
        """Returns the classifier for this domain."""

    def getMapper(name):
        """Returns a named mapper."""


=== Added File Products/AdaptableStorage/serial/interfaces/IEventBase.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Event interface base.

$Id: IEventBase.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface

class IEventBase (Interface):

    def setAspectName(name):
        """Sets the name of the aspect being (de)serialized."""

    def getAspectName():
        """Returns the name of the aspect being (de)serialized."""

    def getObjectMapper():
        """Returns the object mapper for the object being (de)serialized."""

    def getKey():
        """Returns the key of the object being serialized/deserialized."""

    def getObject():
        """Returns the object being serialized."""



=== Added File Products/AdaptableStorage/serial/interfaces/IFullDeserializationEvent.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Full deserialization event interface.

$Id: IFullDeserializationEvent.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from IDeserializationEvent import IDeserializationEvent


class IFullDeserializationEvent(IDeserializationEvent):
    """Deserialization event with features for deserializing internal refs
    """

    def loadInternalReference(ref):
        """Returns an object for a reference of the form (aspect_name, name).
        """


=== Added File Products/AdaptableStorage/serial/interfaces/IFullSerializationEvent.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Full serialization event interface.

$Id: IFullSerializationEvent.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from ISerializationEvent import ISerializationEvent


class IFullSerializationEvent(ISerializationEvent):
    """Serialization event with features for ensuring complete serialization
    """

    def getSerializedAttributeNames():
        """Returns the name of all attributes serialized."""

    def getInternalReference(ob):
        """Returns (aspect_name, name) or None."""



=== Added File Products/AdaptableStorage/serial/interfaces/IGateway.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Gateway interface declaration

$Id: IGateway.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface


class IGateway (Interface):
    """Loads and stores data by key.

    Implementations can store in entire tables, pieces of tables, translate
    for storage in joined tables, or store in some entirely different way.

    See http://www.martinfowler.com/isa/gateway.html and
    http://www.martinfowler.com/isa/tableDataGateway.html
    """

    def getSchema():
        """Returns the ISchema of data stored by this gateway.

        See serial.interfaces.ISchema.
        """

    def load(object_mapper, key):
        """Loads data.

        Returns a pair containing the data and an object
        that acts as a serial number or a hash of the data.
        The serial number is either a time stamp or some other object
        that can be consistently compared to detect conflicts.
        """

    def store(object_mapper, key, data):
        """Stores data.

        Returns a new serial.
        """


=== Added File Products/AdaptableStorage/serial/interfaces/IKeyedObjectSystem.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""IKeyedObjectSystem interface

$Id: IKeyedObjectSystem.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface

class IKeyedObjectSystem (Interface):
    """A collection of objects identifiable by key."""

    def loadStub(mapper_name, key, class_info=None):
        """Returns a class instance, possibly ghosted.

        class_info is provided as a possible optimization.  Without
        it, this method may have to load a full object rather than a
        ghosted object.
        """

    def identifyObject(object):
        """Returns the (mapper_name, key) of an object.

        Returns None if the object is not in the keyed object system.
        """

    def newKey():
        """Returns a new key that doesn't conflict with any other key."""



=== Added File Products/AdaptableStorage/serial/interfaces/IObjectGateway.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Object gateway interface declaration

$Id: IObjectGateway.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from IGateway import IGateway


class IObjectGateway (IGateway):

    def makeKey(event, name, stored):
        """Returns a key for referring to an object stored by this gateway.

        'event' is an IEventBase.  The name of the subobject is in
        'name'.  'stored' is a flag.  If it is true, the key will be
        stored and arbitrary keys are allowed.  If it is false, the
        key will not be stored and keys must be derived exclusively
        from event and name.
        """



=== Added File Products/AdaptableStorage/serial/interfaces/IObjectMapper.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Object mapper interface

$Id: IObjectMapper.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface


class IObjectMapper (Interface):
    """A hub for operations involved in mapping a certain kind of object.
    """

    def getDomainMapper():
        """Returns the domain mapper.

        Note that every object mapper in a domain mapper must return
        the same domain mapper.  Otherwise it's not possible to find
        an object mapper given nothing other than a mapper name.
        """

    def getClassifier():
        """Returns the classifier for subobjects.

        Although object mappers are bound to a specific domain mapper,
        object mappers can provide different classifiers.  This allows
        different branches of an object tree to store data in different
        ways, even though the same classes are used.
        """

    def getSerializer():
        """Returns the IObjectSerializer for this mapper."""

    def getGateway():
        """Returns the IGateway for this mapper."""

    def isVolatile():
        """Returns true if objects should last only one transaction.
        """



=== Added File Products/AdaptableStorage/serial/interfaces/IObjectSerializer.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Serialization / deserialization interfaces.

$Id: IObjectSerializer.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface


class IObjectSerializer(Interface):
    """Serializes/deserializes objects.

    The serialized state does not need to include the class of the object,
    which is saved separately.
    """

    def getSchema():
        """Returns the schema of states (de)serialized by this object.
        """

    def canSerialize(object):
        """Returns true if this mapper can serialize the given object.
        """

    def serialize(object_mapper, key, object, keyed_ob_sys):
        """Returns the serialization of an object.

        Returns a pair containing the serialized state of the object
        and a list of externally referenced objects of the form
        (mapper_name, key, object).  The serialized state should be a
        dictionary mapping aspect names to the serialization of the
        corresponding aspects.
        """

    def deserialize(object_mapper, key, object, keyed_ob_sys, full_state):
        """Fills an object based on a previously serialized state.
        """

    def getClassInfo(full_state=None):
        """Returns the class info for a state.

        If this serializer works with instances of only one class,
        getClassInfo() should return the corresponding class info even
        when full_state is None to improve performance.  Otherwise,
        when full_state is None, getClassInfo() should return None.

        The class info takes the form ((module, name), args), where
        args is usually None, but may be the arguments for
        constructing the class.
        """



=== Added File Products/AdaptableStorage/serial/interfaces/ISchema.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Data schema interface.

$Id: ISchema.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from Interface import Interface

class ISchema(Interface):
    """Data schema"""

    def __eq__(other):
        """Checks equality with another schema.

        The idea is that serializers and data gateways need to agree
        on schemas, and this method allows you to check compatibility.
        """


=== Added File Products/AdaptableStorage/serial/interfaces/ISerializationEvent.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Serialization event interface.

$Id: ISerializationEvent.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from IEventBase import IEventBase


class ISerializationEvent(IEventBase):
    """Serialization event.

    Aspect serializers call methods of this interface to create
    internal and external references.
    """

    def notifySerialized(name, value, attribute=0):
        """Indicates that a named internal subobject was serialized.

        This allows a 'remainder pickler' to refer to subobjects by name.
        Be careful to unwrap acquisition and/or context wrappers around
        subob before calling this method.
        """

    def classifyObject(value):
        """Returns a classification and mapper_name given a subobject.
        """

    def notifySerializedRef(name, value, attribute=0,
                            mapper_name=None, key=None, stored_key=0):
        """Indicates that a reference to an external subobject was serialized.

        TODO: write more here. ;-)
        """

    def ignoreAttribute(name):
        """Indicates that an attribute should be ignored when storing."""

    def getExternalRefs():
        """Returns the list of external references.

        The returned list is of the form [(mapper_name, key, subobject)].
        """


=== Added File Products/AdaptableStorage/serial/interfaces/__init__.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Serialization framework interfaces package

$Id: __init__.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""


=== Added File Products/AdaptableStorage/serial/interfaces/public.py ===
##############################################################################
#
# Copyright (c) 2002 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.
#
##############################################################################
"""Public interfaces

$Id: public.py,v 1.1 2002/11/27 18:37:06 shane Exp $
"""

from IAspectSerializer import IAspectSerializer
from IClassifier import IClassifier
from IDeserializationEvent import IDeserializationEvent
from IDomainMapper import IDomainMapper
from IEventBase import IEventBase
from IFullDeserializationEvent import IFullDeserializationEvent
from IFullSerializationEvent import IFullSerializationEvent
from IGateway import IGateway
from IKeyedObjectSystem import IKeyedObjectSystem
from IObjectGateway import IObjectGateway
from IObjectMapper import IObjectMapper
from IObjectSerializer import IObjectSerializer
from ISchema import ISchema
from ISerializationEvent import ISerializationEvent