module CloudBackup

  # Abstract driver for cloud-backups.
  #
  # This class is thought as an interface, it encapsulates the
  # abstract logic of a backup and let's child-classes *drivers*
  # implement the details of how to communicate to a specific storage
  # engine.
  #
  class Driver

    # Driver Initializer
    #
    # Each driver will probably have different parameters, api-keys
    # authentication methods etc.
    #
    # Thus, initialization must be handled/implemented by child classes
    #
    def initialize
      raise Error.must_define :initialize
    end

    # Initiate backup
    #
    # This callback is reserved to initiate server connections or
    # specific per-driver initialization.
    #
    def initiate
      raise Error.must_define :initiate
    end

    # Driver Identificator
    #
    # Specifies the *identificator* where the resources will be
    # installed.
    #
    # For example: If you are storing data into Google-Storage, or
    # S3 this could be a bucket-name.
    #
    # Note: each driver may specify different types of identificators
    # or implement it's own methods depending on the storage-engine
    # that is being used.
    #
    def identificator
      raise Error.must_define :identificator
    end

    # Identificator changer
    #
    # Allows the client to change the identificator
    #
    def identificator name
      raise Error.must_define :identificator=
    end

    # File aggregator
    #
    # Adds a file to be backed up by the driver, path might be an
    # *absolute* or *relative* depending on how you are running your
    # script.
    #
    # *absolute* paths are recommendend
    #
    def add_file path
      @files ||= []
      @files << path
    end

    # Uncommited files
    #
    # Returns a list of files that have not been backed up, but were
    # passed by the *add_file* method. to be backed-up!
    #
    def list
      @files ||= []
    end

    # Lists backed-up files ordered by date.
    #
    # Must return a list of all files that exist in the *Remote-Storage-Engine*
    # as an array, ordered by date!
    #
    # Note: (FIFO)
    #
    def list_by_date
      raise Error.must_define :list_by_date
    end

    # Remote resource remover
    #
    # Deletes a remote resource, normally this is thought to remove
    # resources after new ones are beinng added
    #
    def remove name
      raise Error.must_define :remove
    end

    # File uploader.
    #
    # Uploads all files that were added to the *queue*
    #
    def upload
      raise Error.must_define :upload
    end

    # Termination callback
    #
    # This method is called after all other methods are called, right
    # before terminating execution. You might wana use this to close
    # connections to remote servers.
    #
    # Also. Good for notifications!
    #
    def terminate
      raise Error.must_define :terminate
    end

  end

end