"""
    Abstract Service interface
"""

class ServiceError (Exception) :
    """
        Service-related error.
    """

class Service (object) :
    """
        A Service listens for incoming connections, handing those connections off as separate objects.

        This is an abstract base class that is further impemented by e.g. TCP or SSL.
    """

    def __init__ (self, endpoint) :
        """
            Listen on the given local endpoint.

                endpoint    - the local Endpoint to provide this service on.
        """

        raise NotImplementedError()

    def accept (self, cls=None) :
        """
            Accept and return a new Transport object representing a connected remote Client.

                cls         - optional transport-specific type to use for the new connection.
        """

        raise NotImplementedError()
    
    def close (self) :
        """
            Explicitly shut down this Service, closing any underlying resources and refusing any new connections.

            This will happen implicitly if the Service is destroyed, this is just the explicit interface.

            This invalidates this Service object for future use.

            This may, in theory, raise an error, which would be supressed if this Service were destroyed.
        """
        
        raise NotImplementedError()