# Copyright (c) 2004 Infrae. All rights reserved.
# See also LICENSE.txt

from Interface import Interface

class IRailroadService(Interface):
    """
    """

    def __init__(repository_url, services_url, repository_name, client_name):
        """Create a service instance
        
        Raises InvalidURLError if services_url or repository_url do not
        end with a slash.
        """
        pass
    
    # ACCESSORS

    def get_railroad_service(self):
        """Useful to get to this service through acquisistion
        """
        pass
    
    def repository_url():
        """Return the base URL of the Railroad repository.
        
        This URL will end in a slash, since it is a 'collection'.
        """
        pass

    def services_url():
        """Return the base URL for the Railroad services.
        
        This URL will end in a slash, since it is a 'collection'.
        """
        pass

    def repository_name():
        """Return the name the storage was configured with.
        """
        pass

    def client_name():
        """Return the name this CMS is registered with on the 
        Railroad server.
        """
        pass

    def generate_unique_id(type=None):
        """Return a UUID as 36 character string.

        The optional type parameter defines which type of
        UUID is generated. Possible values are:
          1. time - time based UUID (default)
          2. random - completely random UUID
          3. choose - server systems choice
        """
        pass
    
    def resource_url_for(proxy):
        """Return the repository URL for the given proxy object.
        
        This is the canonical way to get the URL to the resource.

        The url is constructed out of the configured repository URL
        and the path of the resource on the repository.
        
        Raises ProxyNotAssignedError if there is no resource assigned to 
        this proxy.
        
        This URL will not end in a slash, since it is a 'resource'.
        """
        pass
    
    def proxy_for_unique_id(unique_id):
        """Get the Railroad proxy object for this unique id.
        
        Raises ProxyNotFoundError if there not proxy for this unique id.
        """
        pass
    
    def fetch_properties_for(proxy, user=None, pw=None):
        """Return a dict with all WebDAV properties (in unicode)
        
        Raises ProxyNotAssignedError if there is no resource assigned to 
        this proxy.
        """
        pass
    
    # AUTHORIZATION
    
    def authorize(unique_id, method='GET'):
        """Check if the proxy with the given unique id allows the
        request specified by method.
        """
        pass
    
     # MANIPULATORS

    def register_proxy(proxy):
        """Register the given proxy object with this service instance.

        The registration allow the mapping between the unique id of the
        proxy object and the object itself.
        
        See proxy_for_unique_id.
        """
        pass

    def unregister_proxy(proxy):
        """Unregister (forget) the given proxy object.

        The mapping for the proxy is removed from this service instance.
        """
        pass

    def set_properties_for(proxy, props, user=None, pw=None):
        """Set WebDAV properties where props is a dict with unicode
        keys and value.

        The keys are tuples in the form of (name, namespace-uri).
        
        Raises ProxyNotAssignedError if there no resource assigned
        to this proxy.
        """
        pass
    
class IRailroadProxy(Interface):
    """
    """
    
    # ACCESSORS

    def unique_id():
        """Return the unique id of this proxy.
        """
        pass

    def has_resource():
        """Return True if this proxy has a resource assigned, otherwise
        return False
        """
        pass

    def is_associated_to_service():
        """Return True if this proxy has been associated to a 
        Railroad Service. Return False otherwise.
        """
        pass
    
    def get_railroad_service():
        """Return the railroad_service object used for this proxy.

        Raises ServiceNotFoundError when this proxy is not
        associated with a service.
        """
        pass
        
    def resource_path():
        """The path portion of the URL of the resource on the 
        Railroad server.
        
        Return None if there is no resource associated with this proxy.        
        """
        pass
    
    def resource_url():
        """Return the full URL of the resource this proxy refers to.
        
        Raises ProxyNotAssignedError if there is no resource assigned
        to this proxy.
        
        This URL will not end in a slash, since it is a 'resource'.
        """
        pass

    def fetch_properties():
        """Returns all properties as stored for the resource assigned
        to this proxy. Keys and values will be in unicode.
        
        Raises ProxyNotAssignedError if there is no resource assigned
        to this proxy.
        """
        pass
    
    # MANIPULATORS

    def set_railroad_service(service):
        """Associate the resource to a railroad_service.
        
        This should also assure the proxy is properly registered
        at this service and unregistered from the 'previous' service if
        appropiate.
        """
        pass
    
    def set_resource_path(resource_path):
        """Assign a resource to this proxy.
        
        resource_path is the path portion of the URL of the resource on the
        Railroad server.
        
        Raises InvalidPathError if path is not relative.
        """
        pass

    def set_properties(property_dict):
        """Stores properties on the resource assigned to this proxy.
        
        Keys and values of the property_dict should be unicode.
        
        Raises ProxyNotAssignedError if there is no resource assigned
        to this proxy.
        """
        pass

    # RAILROAD EVENTS
    
    def on_upload_succeeded(resource_url, errormsg):
        """Notifies proxy of a succesful resource upload to the Railroad
        repository.
        
        Method should be publishable (i.e., the implementation needs
        to have a doc string).
        """
        pass
    
    def on_upload_failed(errormsg):
        """Notifies proxy of a failed resource upload to the Railroad
        repository.
        
        Method should be publishable (i.e., the implementation needs
        to have a doc string).
        """
        pass
    
    # ZOPE EVENTS
    
    def on_create():
        """Should be called when this proxy was just created.
        """
        pass
    
    def on_paste():
        """Should be called just after this proxy has been pasted to its 
        destination.
        """
        pass
    
    def on_delete():
        """Should be called just *before* this proxy is deleted.
        """
        pass