# HG changeset patch
# User Thierry Florac <tflorac@ulthar.net>
# Date 1549356031 -3600
# Node ID 4eb49f19314aa6ffd623241faf43208630b7403c
# Parent  ab573883a5c701089e3f3dc07eff9a6f16ddd224
Added blobs references manager interface

diff -r ab573883a5c7 -r 4eb49f19314a src/pyams_file/interfaces/__init__.py
--- a/src/pyams_file/interfaces/__init__.py	Tue Feb 05 09:39:36 2019 +0100
+++ b/src/pyams_file/interfaces/__init__.py	Tue Feb 05 09:40:31 2019 +0100
@@ -12,21 +12,40 @@
 
 __docformat__ = 'restructuredtext'
 
-
-# import standard library
-
-# import interfaces
 from z3c.form.interfaces import IFileWidget as IBaseFileWidget
 from zope.annotation.interfaces import IAttributeAnnotatable
+from zope.interface import Attribute, Interface, implementer
+from zope.lifecycleevent import ObjectModifiedEvent
 from zope.lifecycleevent.interfaces import IObjectModifiedEvent
+from zope.schema import Bytes, BytesLine, Choice, Int, Text, TextLine
 from zope.schema.interfaces import IBytes
 
-# import packages
-from zope.interface import implementer, Interface, Attribute
-from zope.lifecycleevent import ObjectModifiedEvent
-from zope.schema import Bytes, BytesLine, Int, Text, TextLine, Choice
+from pyams_file import _
+
+
+#
+# Blobs references manager
+#
+
+class IBlobReferenceManager(Interface):
+    """Blobs references manager
 
-from pyams_file import _
+    This utility interface is used to manage references to blobs: each file contains a
+    link to a ZODB "Blob" object which is used to store it's data; when a content is duplicated,
+    all it's blobs references are updated but the blob itself is not duplicated to reduce space usage.
+    As long as a blob data is not modified, the same content can be shared between several versions
+    of a same content. So it's only when all references to a given blob have been removed that
+    the blob file is deleted and can be garbaged collected.
+    """
+
+    def add_reference(self, blob, reference):
+        """Add a reference to given blob"""
+
+    def drop_reference(self, blob, reference):
+        """Remove reference from given blob
+
+        Blob is deleted if no more referenced.
+        """
 
 
 #
@@ -63,6 +82,12 @@
     def get_blob(self, mode='r'):
         """Get Blob file associated with this object"""
 
+    def add_blob_reference(self, reference):
+        """Add a reference to file internal blob"""
+
+    def free_blob(self):
+        """Free blob associated with this object"""
+
 
 class IMediaFile(IFile):
     """Multimedia file"""