# -*- coding: UTF-8 -*-
#    This file is part of arena.
#
#    arena is free software: you can redistribute it and/or modify it
#    under the terms of the GNU General Public License as published by the
#    Free Software Foundation; either version 3 of the License or, at your
#    option, any later version.
#
#    arena is distributed in the hope that it will be useful, but
#    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABLITY
#    or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
#    License for more details.
#
#    You should have received a copy of the GNU General Public License along
#    with arena.  If not, see <http://www.gnu.org/licenses/>.

## @file
#  This file defines a basic content provider class, from which all other
#  content providers for arena should descend.

from Library.Base.Events import ALoggingEventfulObject
from Library.IO.Logging.Logs import AMessageWithTimeStamp

## Events generated by a content provider
cpEvents = {
    # Before content is fetched by the provider
    "fetchContent": None
}

## A content provider error
class AContentProviderError(AMessageWithTimeStamp):
    pass

## A content provider.
#
#  A content provider is one of the three major classes that make up arena.
#  A content provider is responsible for loading content from a source and
#  returning an iterable object that will allow a view to format and display
#  that content to the client.
class AContentProvider(ALoggingEventfulObject):
    ## Constructor
    #
    #  The constructor expects that \p params will contain the following items:
    #  - \p Mediator -- A reference to the content mediator that has 
    #                   constructed the content provider instance.
    def __init__(Self, **params):
        ALoggingEventfulObject.__init__(Self, **params)
        
        if "Mediator" in Self._params:
            Self._Mediator = Self._params["Mediator"]
            del Self._params["Mediator"]
        
    ## Initializer
    def init(Self):
        result = ALoggingEventfulObject.init(Self)
        
        if result:
            # Establish private attributes
            # The mediator that constructed the content provider.
            Self._Mediator = None
            # The events generated by a content provider
            Self._events.update(cpEvents)
            
        return result
        
    # Properties ---------------------------------------------------------------
    ## Retrieve the content from the content provider.
    #
    #  This method should be implemented by descendant classes.  It should
    #  return an iterable object that contains content which will be passed to
    #  a view for display.  If there is no content to display, an empty
    #  iterable object should be returned.
    #
    #  This method generates the \p fetchContent event.
    def content(Self):
        result = tuple()
        
        Event = Self.generate("fetchContent")
        if Event.handled():
            result = Event.result()
            
        del Event
        
        return result
        
    ## Retrieve the mediator responsible for constructing the content provider.
    def Mediator(Self):
        return Self._Mediator

