# -*- coding: utf-8 -*-
##############################################################################
#
# Copyright (c) 2009 Nexedi SA and Contributors. All Rights Reserved.
#                    Jean-Paul Smets-Solanes <jp@nexedi.com>
#
# WARNING: This program as such is intended to be used by professional
# programmers who take the whole responsability of assessing all potential
# consequences resulting from its eventual inadequacies and bugs
# End users who are looking for a ready-to-use solution with commercial
# garantees and support are strongly adviced to contract a Free Software
# Service Company
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
#
##############################################################################

from zope.interface import Interface

class IMetadataDiscoverable(Interface):
  """
  Metadata Discoverable interface specification

  Documents which implement IMetadataDiscoverable provide
  methods to discover and update metadata properties
  from content, user input, file name, etc.
  """

  def getContentInformation():
    """
    Returns all possible metadata which can be extracted 
    from the document content (ex. title from an HTML file,
    creation date from a PDF document, etc.)
    """

  def getPropertyDictFromUserLogin(user_login=None):
    """
    Based on the user_login, find out all properties which
    can be discovered to later update document metadata.

    user_login -- optional user login ID
    """

  def getPropertyDictFromContent():
    """
    Base on the result of getContentInformation, find out all
    properties which can be discovered to later update document metadata.
    """

  def getPropertyDictFromFileName(file_name):
    """
    Based on the file name, find out all properties which
    can be discovered to later update document metadata.

    file_name -- file name to use in discovery process
    """

  def getPropertyDictFromInput():
    """
    Based on the user input, find out all properties which
    can be discovered to later update document metadata.
    """

  def discoverMetadata(file_name=None, user_login=None):
    """
    Updates the document metadata by discovering metadata from
    the user login, the document content, the file name and the
    user input. The order of discovery should be set in system
    preferences.

    file_name - optionnal file name (ex. AA-BBB-CCC-223-en.doc)

    user_login -- optional user login ID

    XXX - it is unclear if this method should also trigger finishIngestion
          and whether this should be documented here or not
    """

  def finishIngestion():
    """
    Finish the ingestion process (ex. allocate a reference number automatically if
    no reference was defined.)

    XXX - it is unclear if this method should be part of the interface
    """