[Zope-CVS] CVS: Products/Scheduler/interfaces - IScheduler.py:1.1

[Tres Seaver]

Update of /cvs-repository/Products/Scheduler/interfaces
In directory cvs.zope.org:/tmp/cvs-serv514/interfaces

Added Files:
	IScheduler.py 
Log Message:


  - Move IScheduler into sub-package.

  - Export individual interfaces by name from top-level product, e.g.
    clients should use::

      from Products.Scheduler import IScheduler

    to gain access to the IScheduler interface.


=== Added File Products/Scheduler/interfaces/IScheduler.py ===
##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors.
# All Rights Reserved.
# 
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
# 
##############################################################################
"""

Revision information:
$Id: IScheduler.py,v 1.1 2002/09/29 19:34:26 tseaver Exp $
"""

import Interface
from Interface import Attribute
from Products.Event.IEvent import IFilterableEvent
from Products.Event.ISubscriber import ISubscriber
from Products.Event.EventRegistry import eventRegistry

class IScheduler(ISubscriber):
    """Schedule objects manage and fire scheduled events

    The schedule subscibes to ITimeEvent events. It fires
    scheduled events only when it receives time events.

    This interface only allows scheduling of scheduled events and
    notification of time events.

    A schedule could provide additional or extended interfaces to
    support management applications.

    The scheduler doesn't provide custom or variable scheduling
    policies. For example, there isn't any specific support for
    recurring events or for handling event retry on error. These
    policies are handled by events themselves. 
    
    """

    def schedule(time, event):
        """Schedule an IScheduledEvent.

        The time argument is a "time.time", or an ITime object.
        """

class IScheduledEvent(IFilterableEvent):
    """Scheduler tick events."""

    # XXX Maybe we need a way to return time deltas, so that we can
    # say N seconds in the future, whenever that is.

    def __call__():
        """Execute the event.

        (The event will be called in the scheduler's acquisition context.)

        There is normally no return value. If there is an error and a
        retry is needed, then a time.time and a new event to do the
        retry should be returned as a tuple.

        The event should not raise an exception. Raising an exception
        is viewed as an error. Note that any exceptions raised will be
        ignored, but may be logged.
        """

    def next():
        """Return the next scheduled time and event

        This method is used to implement recuring events.

        If a time and event is returned, the event will be scheduled at the
        indicated time.

        If the reciever is a one-time event, or should otherwise no-longer
        recur, then None is returned.

        Note that this method may be called multiple times without executing
        the returned event to build representations of event schedules.
        """

    def getTime():
        """
        Return the time that this event wants to be scheduled for
        """

    def getInfo():
        """
        Return string describing the task's event-specific processing details.
        """

    def getDescription():
        """
        Return short description of the event.
        
        This should include what the event does and, if the event is
        recuring, how the event recurs.
        """

    def getTime():
        """
        Return the time scheduled for the event.
        """

eventRegistry.registerEvent(IScheduledEvent, 'Schedule ticks')

class IDescheduledEvent(IFilterableEvent):
    def getTime():
        """
        Return the time that this event wants to be descheduled from
        """

class ITimeEvent(Interface.Base):
    """Event occurring at a moment in time."""

    def getTime():
        """Get the event time.

        The event time is a "time.time" value.
        """

eventRegistry.registerEvent(ITimeEvent, 'Time ticks')