##
## jambtables.py
## Login : <uli@pu.smp.net>
## Started on  Tue Jun 22 06:31:42 2010 Uli Fouquet
## $Id$
## 
## Copyright (C) 2010 Uli Fouquet
## This program 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 2 of the License, or
## (at your option) any later version.
## 
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY 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 this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##
"""WAeUP SIRP support for JAMB tables.

JAMB tables are datasets delivered by JAMB, normally as CSV files.
"""
import grok
from waeup.sirp.interfaces import IWAeUPSIRPPluggable
from waeup.sirp.applicants.jambtables.interfaces import (
    IJAMBDataRoot
    )

class JAMBDataRoot(grok.Container):
    """A root folder for JAMB data.

    JAMB data is normally imported as a set of
    :class:`waeup.sirp.applicants.applicants.Applicant` instances, but
    this depends on the importer used which is not part of the
    container itself.

    The :class:`JAMBDataRoot` makes no special assumptions about how
    data is stored inside, while we should keep in mind that regular
    strings are the most effective way to store/retrieve data inside a
    :class:`grok.Container`.

    In a regular 'waeup.sirp' site we normally provide a
    `JAMBDataRoot` instance named ``jambdata`` in the site
    root. I.e. when you create a :class:`waeup.sirp` university
    instance, a `JAMBDataRoot` is created automatically (by
    :class:`JAMBDataPlugin`) under the name ``jambdata``.
    
    .. seealso:: waeup.sirp.applicant.jambdata.batching.JAMBDataImporter
    """
    grok.implements(IJAMBDataRoot)
    
class JAMBDataPlugin(grok.GlobalUtility):
    """A WAeUPSIRPPlugin that creates a JAMB data root in portal.

    This plugin should be called by a typical
    `waeup.sirp.app.Universtiy` instance on creation time. The
    :meth:`update` method normally can also be triggered manually over
    the main site configuration.

    Implements :class:`waeup.sirp.interfaces.IWAeUPSIRPPluggable`
    """
    grok.name('jambdata')
    grok.implements(IWAeUPSIRPPluggable)
    log_prefix = 'JAMBDataPlugin'

    def setup(self, site, name, logger):
        """Create a new :class:`ApplicantsRoot` instance in `site`.
        """
        site['jambdata'] = JAMBDataRoot()
        logger.info(
            '%s: Installed JAMB data root.' % (self.log_prefix,)
            )
        return

    def update(self, site, name, logger):
        """Update site wide ``jambdata`` root.

        If the site already contains a suitable ``jambdata`` root,
        leave it that way. If not create one and delete the old one if
        appropriate.
        """
        jamb_folder = site.get('jambdata', None)
        site_name = getattr(site, '__name__', '<Unnamed Site>')
        if IJAMBDataRoot.providedBy(jamb_folder):
            # JAMB data storage up to date. Return.
            logger.info(
                '%s: Updating site at %s: Nothing to do.' % (
                    self.log_prefix, site_name,)
                )
            return
        elif jamb_folder is not None:
            # JAMB data storage needs update. Remove old instance.
            logger.warn(
                '%s: Outdated JAMB data folder detected at site %s.'
                'Removing it.' % (self.log_prefix, site_name)
                    )
            del site['jambdata']
        # Add new applicants.
        logger.info(
            '%s: Updating site at %s. Installing '
            'JAMB data folder.' % (self.log_prefix, site_name,)
            )
        self.setup(site, name, logger)
        return