##
## 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

def get_jambdata(reg_no):
    """Get a JAMB data set stored in site-wide JAMB data folder.

    `reg_no`
        A string. The registration number assigned for the looked up
        applicant.

    It is quite easy to get JAMB datasets from a waeup.sirp site
    'manually' but you are encouraged to use this function instead, as
    the method to store JAMB data might change in future releases.
        
    Returns the applicant data if found or ``None``.
    """
    site = grok.getSite()
    return site['jambdata'].get(reg_no, None)