"""CubicWeb server connections pool :

* the rql repository has a limited number of connections pools, each of them

  dealing with a set of connections on each source used by the repository

* operation may be registered by hooks during a transaction, which will  be

  fired when the pool is commited or rollbacked

This module defined the `ConnectionsPool` class and a set of abstract classes

for operation.

:organization: Logilab

:copyright: 2001-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

"""

__docformat__ = "restructuredtext en"

import sys

class ConnectionsPool(object):

    """handle connections on a set of sources, at some point associated to a

    user session

    """

    def __init__(self, sources):

        # dictionnary of (source, connection), indexed by sources'uri

        self.source_cnxs = {}

        for source in sources:

            self.source_cnxs[source.uri] = (source, source.get_connection())

        if not 'system' in self.source_cnxs:

            self.source_cnxs['system'] = self.source_cnxs[sources[0].uri]

        self._cursors = {}

    def commit(self):

        """commit the current transaction for this user"""

        # FIXME: what happends if a commit fail

        # would need a two phases commit or like, but I don't know how to do

        # this using the db-api...

        for source, cnx in self.source_cnxs.values():

            # let exception propagates

            cnx.commit()

    def rollback(self):

        """rollback the current transaction for this user"""

        for source, cnx in self.source_cnxs.values():

            # catch exceptions, rollback other sources anyway

            try:

                cnx.rollback()

            except:

                source.critical('rollback error', exc_info=sys.exc_info())

    def close(self, i_know_what_i_do=False):

        """close all connections in the pool"""

        if i_know_what_i_do is not True: # unexpected closing safety belt

            raise RuntimeError('pool shouldn\'t be closed')

        for cu in self._cursors.values():

            try:

                cu.close()

            except:

                continue

        for _, cnx in self.source_cnxs.values():

            try:

                cnx.close()

            except:

                continue

    # internals ###############################################################

    def pool_set(self, session):

        """pool is being set"""

        self.check_connections()

    def pool_reset(self, session):

        """pool is being reseted"""

        for source, cnx in self.source_cnxs.values():

            source.pool_reset(cnx)

    def __getitem__(self, uri):

        """subscription notation provide access to sources'cursors"""

        try:

            cursor = self._cursors[uri]

        except KeyError:

            cursor = self.source_cnxs[uri][1].cursor()

            if cursor is not None:

                # None possible on sources without cursor support such as ldap

                self._cursors[uri] = cursor

        return cursor

    def sources(self):

        """return the source objects handled by this pool"""

        # implementation details of flying insert requires the system source

        # first

        yield self.source_cnxs['system']

        for uri, (source, cursor) in self.source_cnxs.items():

            if uri == 'system':

                continue

            yield source

        #return [source_cnx[0] for source_cnx in self.source_cnxs.values()]

    def source(self, uid):

        """return the source object with the given uri"""

        return self.source_cnxs[uid][0]

    def connection(self, uid):

        """return the connection on the source object with the given uri"""

        return self.source_cnxs[uid][1]

    def reconnect(self, source):

        """reopen a connection for this source"""

        source.info('trying to reconnect')

        self.source_cnxs[source.uri] = (source, source.get_connection())        

        del self._cursors[source.uri]

    def check_connections(self):

        for source, cnx in self.source_cnxs.itervalues():

            newcnx = source.check_connection(cnx)

            if newcnx is not None:

                self.reset_connection(source, newcnx)

    def reset_connection(self, source, cnx):

        self.source_cnxs[source.uri] = (source, cnx)

        self._cursors.pop(source.uri, None)

class Operation(object):

    """an operation is triggered on connections pool events related to

    commit / rollback transations. Possible events are:

    precommit:

      the pool is preparing to commit. You shouldn't do anything things which

      has to be reverted if the commit fail at this point, but you can freely

      do any heavy computation or raise an exception if the commit can't go.

      You can add some new operation during this phase but their precommit

      event won't be triggered

    commit:

      the pool is preparing to commit. You should avoid to do to expensive

      stuff or something that may cause an exception in this event

    revertcommit:

      if an operation failed while commited, this event is triggered for

      all operations which had their commit event already to let them

      revert things (including the operation which made fail the commit)

    rollback:

      the transaction has been either rollbacked either

      * intentionaly

      * a precommit event failed, all operations are rollbacked

      * a commit event failed, all operations which are not been triggered for

        commit are rollbacked

    order of operations may be important, and is controlled according to:

    * operation's class

    """

    def __init__(self, session, **kwargs):

        self.session = session

        self.user = session.user

        self.repo = session.repo

        self.schema = session.repo.schema

        self.config = session.repo.config

        self.__dict__.update(kwargs)

        self.register(session)

        # execution information

        self.processed = None # 'precommit', 'commit'

        self.failed = False

    def register(self, session):

        session.add_operation(self, self.insert_index())

    def insert_index(self):

        """return the index of  the lastest instance which is not a

        LateOperation instance

        """

        for i, op in enumerate(self.session.pending_operations):

            if isinstance(op, (LateOperation, SingleLastOperation)):

                return i

        return None

    def handle_event(self, event):

        """delegate event handling to the opertaion"""

        getattr(self, event)()

    def precommit_event(self):

        """the observed connections pool is preparing a commit"""

    def revertprecommit_event(self):

        """an error went when pre-commiting this operation or a later one

        should revert pre-commit's changes but take care, they may have not

        been all considered if it's this operation which failed

        """

    def commit_event(self):

        """the observed connections pool is commiting"""

        raise NotImplementedError()

    def revertcommit_event(self):

        """an error went when commiting this operation or a later one

        should revert commit's changes but take care, they may have not

        been all considered if it's this operation which failed

        """

    def rollback_event(self):

        """the observed connections pool has been rollbacked

        do nothing by default, the operation will just be removed from the pool

        operation list

        """

class PreCommitOperation(Operation):

    """base class for operation only defining a precommit operation

    """

    def precommit_event(self):

        """the observed connections pool is preparing a commit"""

        raise NotImplementedError()

    def commit_event(self):

        """the observed connections pool is commiting"""

class LateOperation(Operation):

    """special operation which should be called after all possible (ie non late)

    operations

    """    

    def insert_index(self):

        """return the index of  the lastest instance which is not a

        SingleLastOperation instance

        """

        for i, op in enumerate(self.session.pending_operations):

            if isinstance(op, SingleLastOperation):

                return i

        return None

class SingleOperation(Operation):

    """special operation which should be called once"""    

    def register(self, session):

        """override register to handle cases where this operation has already

        been added

        """

        operations = session.pending_operations

        index = self.equivalent_index(operations)

        if index is not None:

            equivalent = operations.pop(index)

        else:

            equivalent = None

        session.add_operation(self, self.insert_index())

        return equivalent

    def equivalent_index(self, operations):

        """return the index of the equivalent operation if any"""

        equivalents = [i for i, op in enumerate(operations)

                       if op.__class__ is self.__class__]

        if equivalents:

            return equivalents[0]

        return None

class SingleLastOperation(SingleOperation):

    """special operation which should be called once and after all other

    operations

    """    

    def insert_index(self):

        return None

from logging import getLogger

from cubicweb import set_log_methods

set_log_methods(Operation, getLogger('cubicweb.session'))