"""
$RCSfile: interfaces.py,v $

Product interfaces

Author: Philipp von Weitershausen <philikon@philikon.de>

$Id: interfaces.py,v 1.3 2003/06/16 05:47:53 arielpartners Exp $
"""

__cvstag__  = '$Name:  $'[6:-2]
__date__    = '$Date: 2003/06/16 05:47:53 $'[6:-2]
__version__ = '$Revision: 1.3 $'[10:-2]

from zope.interface import Interface

class IXMLMethod(Interface):
    """
    Base Method interface.  Classes never implement this
    interface directly, only derived interfaces.
    """

    def availableProcessors():
        """
        Return names of currently available processor libraries
        """

    def processor():
        """
        Obtain the object encapsulating the selected processor.
        """

    def getXmlSourceObject():
        """
        Retrieves the source Zope object (for XML content) via
        acquisition.
        """

    def setDebugLevel(debugLevel):
        "same as changing the property.  For use in scripts"

    def isDebugging():
        "Return true if and only if debugging is on."

    def behaveLikeList():
        """
        Return list of meta types for standard zope objects this
        method can behave like
        """

class IDTDValidateMethod(IXMLMethod):
    """
    Automatically validates an XML document against its DTD, where the
    XML document is obtained from another Zope object via acquisition.
    """

    def validationResultsString(REQUEST):
        "Return results of validation as a string"

    def isValid(REQUEST):
        """
        Return boolean indicating whether passed in document is valid
        with respect to this DTD
        """

class IXPathMethod(IXMLMethod):
    """
    Automatically filters an XML document via XPath, where the XML
    document is obtained from another Zope object via acquisition.
    """

    def evaluate(REQUEST):
        """
        Generate results using xpath expression and return them as a
        string
        """

class IXSLTMethod(IXMLMethod):
    """
    Automatically transforms an XML document via XSLT, where the XML
    document is obtained from another Zope object via acquisition.
    """

    def getXslTransformer():
        """
        Obtain the Zope object holding the XSLT, or None if the name
        does not point to a valid object.
        """

    def transform(REQUEST):
        "Generate results using transformer and return them as a string"

    def setCachingOn(REQUEST=None):
        "same as changing the property.  For use in scripts"

    def setCachingOff(REQUEST=None):
        "same as changing the property.  For use in scripts"
        
    def isCachingOn():
        "Return TRUE if caching is turned on"

class ICacheManager(Interface):
    """
    XML Method Cache Manager public interface
    """

    def batchSetCachingOn():
        """
        Turns caching on for all instances of all types of XML filters
        within the scope of this cache manager.
        """

    def batchSetCachingOff():
        """
        Turns caching off for all instances of all types of XML
        filters within the scope of this cache manager.

        """

    def cacheFileTimeStamp(url):
        """
        Return the last modified time of the cache file for the passed in
        URL 'url', or 0 if the cache file does not exist
        """

    def valueFromCache(url):
        """
        Retrieve the output from the cache for the passed in
        URL 'url', or None if the cache file does not exist.
        """

    def saveToCache(url, contents):
        """
        Save some contents 'contents' to the cache for the passed in
        URL 'url'.  It will overwrite the previous contents of the cache
        file, or create a new cache file if it does not yet exist.
        """

    def clearCache():
        """
        Clear the cache.  This involves removing every cache file from
        the file system.
        """

    def listCacheFiles():
        """
        Return the list of files in the cache
        """

    ################################################################
    # Below is a section of methods we would like to support
    # but can't yet figure out exactly *how*
    # Suggestions appreciated @@ CKS 3/2/2003
    ################################################################    

#     def regenerateAll():
#         """
#         Forces all usages of all XML filters within the scope of this
#         cache manager to regenerate (transform) their contents.  They
#         may or may not cache the result, depending on their cache
#         settings.
#         """

#     def regenerateIfNeeded():
#         """
#         For all usages of all XML filters within the scope of this
#         cache manager that have caching on, check to see if the cached
#         version of their contents is up to date.  If not, regenerate
#         it and cache it.  This method does not affect those instances
#         of XML filters for which caching is set to off.
#         """

#     def listUpToDate():
#         """
#         List all users of all XML filter instances within the
#         scope of this Cache Manager that are up to date with respect
#         to this cache.
#         """

#     def listOutOfDate():
#         """
#         List all users of all XML filter instances within the scope
#         of this Cache Manager that are out to date with respect to
#         this cache.
#         """

class IGeneratorRegistry(Interface):

    def register(meta_type, obj):
        """
        Register generator object 'obj' for meta type 'meta_type'
        """

    def getGenerator(meta_type):
        """
        Return generator object for meta type 'meta_type'
        """

    def getDefaultGenerator():
        """
        Return default generator object
        """

    def supportedMetaTypes():
        """
        Return a sequence with supported meta types
        """

class IGenerator(Interface):
    """
    Interface for Output Generators
    """

    def createObject(id, title, rawString, **kw):
        """
        Create the object and return its result
        """
    def getResult(obj, client, REQUEST=None, RESPONSE=None):
        """
        Call the object and return its result
        """