##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (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.
#
##############################################################################
"""Placeful internationalization of content objects.

$Id: interfaces.py 25177 2004-06-02 13:17:31Z jim $
"""
from zope.interface import Interface
from zope.i18n.interfaces import ITranslationDomain, IMessageCatalog
from zope.app.container.interfaces import IContainer


class IWriteTranslationDomain(Interface):
    """This interface describes the methods that are necessary for an editable
    Translation Domain to work.

    For a translation domain to be editable its 'messages' have to support
    the following information: id, string, domain, language, date

    Most of the information will be natural, since they are required by the
    translation domain, but especially the date is not a necessary info
    (in fact, it is meta data)
    """

    def getMessage(msgid, langauge):
        """Get the full message of a particular language."""

    def getMessageIds(filter='%'):
        """Get all the message ids of this domain."""

    def getMessages():
        """Get all the messages of this domain."""

    def getAllLanguages():
        """Find all the languages that are available"""

    def getAvailableLanguages():
        """Find all the languages that are available."""

    def addMessage(msgid, msg, language, mod_time=None):
        """Add a message to the translation domain.

        If mod_time is None, then the current time should be inserted.
        """

    def updateMessage(msgid, msg, language, mod_time=None):
        """Update a message in the translation domain.

        If mod_time is None, then the current time should be inserted.
        """

    def deleteMessage(domain, msgid, language):
        """Delete a messahe in the translation domain."""

    def addLanguage(language):
        """Add Language to Translation Domain"""

    def deleteLanguage(language):
        """Delete a Domain from the Translation Domain."""


class ISyncTranslationDomain(Interface):
    """This interface allows translation domains to be synchronized. The
       following four synchronization states can exist:

       0 - uptodate: The two messages are in sync.
                Default Action: Do nothing.

       1 - new: The message exists on the foreign TS, but is locally unknown.
                Default Action: Add the message to the local catalog.

       2 - older: The local version of the message is older than the one on
                the server.
                Default Action: Update the local message.

       3 - newer: The local version is newer than the foreign version.
                Default Action: Do nothing.

       4 - deleted: The message does not exist in the foreign TS.
                Default Action: Delete local version of message/
    """

    def getMessagesMapping(languages, foreign_messages):
        """Creates a mapping of the passed foreign messages and the local ones.
        Returns a status report in a dictionary with keys of the form
        (msgid, domain, language) and values being a tuple of:

        foreign_mod_date, local_mod_date
        """

    def synchronize(messages_mapping):
        """Update the local message catalogs based on the foreign data.
        """


class ILocalTranslationDomain(ITranslationDomain,
                              IWriteTranslationDomain,
                              ISyncTranslationDomain,
                              IContainer):
    """This is the common and full-features translation domain. Almost all
    translation domain implementations will use this interface.

    An exception to this is the GlobalMessageCatalog as it will be read-only.
    """


class ILocalMessageCatalog(IMessageCatalog):
    """If this interfaces is implemented by a message catalog, then we will be
    able to update our messages.

    Note that not all methods here require write access, but they should
    not be required for an IReadMEssageCatalog and are used for editing
    only. Therefore this is the more suitable interface to put them.
    """

    def getFullMessage(msgid):
        """Get the message data and meta data as a nice dictionary. More
        advanced implementation might choose to return an object with
        the data, but the object should then implement IEnumerableMapping.

        An exception is raised if the message id is not found.
        """

    def setMessage(msgid, message, mod_time=None):
        """Set a message to the catalog. If mod_time is None use the current
           time instead as modification time."""

    def deleteMessage(msgid):
        """Delete a message from the catalog."""

    def getMessageIds():
        """Get a list of all the message ids."""

    def getMessages():
        """Get a list of all the messages."""

