##############################################################################
#
# Copyright (c) 2010, 2011, 2012 Vifib SARL and Contributors.
# All Rights Reserved.
#
# WARNING: This program as such is intended to be used by professional
# programmers who take the whole responsibility 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
# guarantees and support are strongly advised 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 Lesser General Public License
# as published by the Free Software Foundation; either version 2.1
# 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 Lesser 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

"""
Note: all strings accepted/returned by the slap library are encoded in UTF-8.
"""


class IException(Interface):
  """
  Classes which implement IException are used to report errors.
  """


class IConnectionError(IException):
  """
  Classes which implement IServerError are used to report a connection problem
  to the slap server.
  """


class IServerError(IException):
  """
  Classes which implement IServerError are used to report unexpected error
  from the slap server.
  """


class INotFoundError(IException):
  """
  Classes which implement INotFoundError are used to report missing
  information on the slap server.
  """


class IResourceNotReady(IException):
  """
  Classes which implement IResourceNotReady are used to report resource not
  ready on the slap server.
  """


class IRequester(Interface):
  """
  Classes which implement IRequester can request software instance to the
  slapgrid server.
  """

  def request(software_release, software_type, partition_reference,
              shared=False, partition_parameter_kw=None, filter_kw=None):
    """
    Request software release instantiation to slapgrid server.

    Returns a new compute partition document, where this software release will
    be installed.

    software_release -- URI of the software release
                        which has to be instantiated

    software_type -- type of component provided by software_release

    partition_reference -- local reference of the instance used by the recipe
                           to identify the instances.

    shared -- boolean to use a shared service

    partition_parameter_kw -- dictionary of parameter used to fill the
                              parameter dictionary of newly created partition.

    filter_kw -- dictionary of filtering parameter to select the requested
                 compute partition.

      compute_node_guid - compute_node of the requested partition
      partition_type - virtio, slave, full, limited
      port - port provided by the requested partition

    Example:
       request('http://example.com/foo/bar', 'typeA', 'mysql_1')
    """

  def getInformation(partition_reference):
    """
    Get information about an existing instance.
    If it is called from a Compute Partition, get information
    about Software Instance of the instance tree.

    partition_reference -- local reference of the instance used by the recipe
                           to identify the instances.
    """


class ISoftwareRelease(Interface):
  """
  Software release interface specification
  """

  def getURI():
    """
    Returns a string representing the URI of the software release.
    """

  def getComputeNodeId():
    """
    Returns a string representing the identifier of the compute_node where the SR
    is installed.
    """

  def getState():
    """
    Returns a string representing the expected state of the software
    installation.

    The result can be: available, destroyed
    """

  def available():
    """
    Notify (to the slapgrid server) that the software release is
    available.
    """

  def building():
    """
    Notify (to the slapgrid server) that the software release is not
    available and under creation.
    """

  def destroyed():
    """
    Notify (to the slapgrid server) that the software installation has
    been correctly destroyed.
    """

  def error(error_log):
    """
    Notify (to the slapgrid server) that the software installation is
    not available and reports an error.

    error_log -- a text describing the error
                 It can be a traceback for example.
    """


class ISoftwareProductCollection(Interface):
  """
  Fake object representing the abstract of all Software Products.
  Can be used to call "Product().mysoftwareproduct", or, simpler,
  "product.mysoftwareproduct", to get the best Software Release URL of the
  Software Product "mysoftwareproduct".

  Example: product.kvm will have the value of the latest Software
  Release URL of KVM.
  """


class IToken(Interface):
  """
  Classes which implement IToken are used by slap to represent
  information about a Token.
  """
  def request():
    """
    Request a token document to slapgrid server.

    Returns a new Token document.
    """


class ISoftwareInstance(Interface):
  """
  Classes which implement ISoftwareRelease are used by slap to represent
  information about a Software Instance.
  """


class IComputePartition(IRequester):
  """
  Compute Partition interface specification

  Classes which implement IComputePartition can propagate the compute_node
  partition state to the SLAPGRID server and request new compute partition
  creation.
  """

  def stopped():
    """
    Notify (to the slapgrid server) that the software instance is
    available and stopped.
    """

  def started():
    """
    Notify (to the slapgrid server) that the software instance is
    available and started.
    """

  def destroyed():
    """
    Notify (to the slapgrid server) that the software instance has
    been correctly destroyed.
    """

  def error(error_log):
    """
    Notify (to the slapgrid server) that the software instance is
    not available and reports an error.

    error_log -- a text describing the error
                 It can be a traceback for example.
    """

  def getId():
    """
    Returns a string representing the identifier of the compute partition
    inside the slapgrid server.
    """

  def getInstanceGuid():
    """
    Returns a string representing the unique identifier of the instance
    inside the slapgrid server.
    """

  def getState():
    """
    Returns a string representing the expected state of the compute partition.

    The result can be: started, stopped, destroyed
    """

  def getAccessStatus():
    """Get latest compute partition Access message state"""

  def getSoftwareRelease():
    """
    Returns the software release associate to the compute partition.

    Raise an INotFoundError if no software release is associated.
    """

  def getInstanceParameterDict():
    """
    Returns a dictionary of instance parameters.

    The contained values can be used to fill the software instantiation
    profile.
    """

  def getConnectionParameterDict():
    """
    Returns a dictionary of connection parameters.

    The contained values are connection parameters of a compute partition.
    """

  def getType():
    """
    Returns the Software Type of the instance.
    """

  def setUsage(usage_log):
    """
    Associate a usage log to the compute partition.
    This method does not report the usage to the slapgrid server. See
    IComputeNode.report.

    usage_log -- a text describing the compute partition usage.
                 It can be an XML for example.
    """

  def bang(log):
    """
    Report a problem detected on a compute partition.
    This will trigger the re-instantiation of all partitions in the instance tree.

    log -- a text explaining why the method was called
    """

  def getCertificate():
    """
    Returns a dictionary containing the authentication certificates
    associated to the compute partition.
    The dictionary keys are:
      key -- value is a SSL key
      certificate -- value is a SSL certificate

    Raise an INotFoundError if no software release is associated.
    """

  def setConnectionDict(connection_dict, slave_reference=None):
    """
    Store the connection parameters associated to a partition.

    connection_dict -- dictionary of parameter used to fill the
                              connection dictionary of the partition.

    slave_reference -- current reference of the slave instance to modify
    """

  def getInstanceParameter(key):
    """
    Returns the instance parameter associated to the key.

    Raise an INotFoundError if no key is defined.

    key -- a string name of the parameter
    """

  def getConnectionParameter(key):
    """
    Return the connection parameter associate to the key.

    Raise an INotFoundError if no key is defined.

    key -- a string name of the parameter
    """

  def rename(partition_reference, slave_reference=None):
    """
    Change the partition reference of a partition

    partition_reference -- new local reference of the instance used by the recipe
                           to identify the instances.

    slave_reference -- current reference of the slave instance to modify
    """

  def getStatus():
    """
    Returns a dictionary containing the latest status of the
    compute partition.
    The dictionary keys are:
      user -- user who reported the latest status
      created_at -- date of the status
      text -- message log of the status
    """

  def getFullHostingIpAddressList():
    """
    Returns a dictionary containing the latest status of the
    compute partition.
    """

  def setComputePartitionRelatedInstanceList(instance_reference_list):
    """
    Set relation between this Instance and all his children.

    instance_reference_list -- list of instances requested by this ComputeNode
                               Partition.
    """


class IComputeNode(Interface):
  """
  Compute Node interface specification

  Classes which implement IComputeNode can fetch information from the slapgrid
  server to know which Software Releases and Software Instances have to be
  installed.
  """

  def getSoftwareReleaseList():
    """
    Returns the list of software release which has to be supplied by the
    compute_node.

    Raise an INotFoundError if compute_node_guid doesn't exist.
    """

  def getComputePartitionList():
    """
    Returns the list of configured compute partitions associated to this
    compute_node.

    Raise an INotFoundError if compute_node_guid doesn't exist.
    """

  def reportUsage(compute_partition_list):
    """
    Report the compute_node usage to the slapgrid server.
    IComputePartition.setUsage has to be called on each compute partition to
    define each usage.

    compute_partition_list -- a list of compute partition for which the usage
                               needs to be reported.
    """

  def bang(log):
    """
    Report a problem detected on a compute_node.
    This will trigger IComputePartition.bang on all instances hosted by the
    ComputeNode.

    log -- a text explaining why the method was called
    """

  def updateConfiguration(configuration_xml):
    """
    Report the current compute_node configuration.

    configuration_xml -- compute_node XML description generated by slapformat
    """

  def getStatus():
    """
    Returns a dictionary containing the latest status of the
    compute_node.
    The dictionary keys are:
      user -- user who reported the latest status
      created_at -- date of the status
      text -- message log of the status
    """

  def generateCertificate():
    """
    Returns a dictionary containing the new certificate files for
    the compute_node.
    The dictionary keys are:
      key -- key file
      certificate -- certificate file

    Raise ValueError is another certificate is already valid.
    """

  def revokeCertificate():
    """
    Revoke current compute_node certificate.

    Raise ValueError is there is not valid certificate.
    """

  def getInformation():
    """
    Get information about current compute_node.
    If it is called from a ComputeNode, get information about itself.
    """


class IOpenOrder(IRequester):
  """
  Open Order interface specification

  Classes which implement Open Order describe which kind of software instances
  is requested by a given client.
  """

  def requestComputeNode(compute_node_reference):
    """
    Request a compute_node to slapgrid server.

    Returns a new compute_node document.

    compute_node_reference -- local reference of the compute_node
    """


class ISupply(Interface):
  """
  Supply interface specification

  Classes which implement Supply describe which kind of software releases
  a given client is ready to supply.
  """

  def supply(software_release, compute_node_guid=None):
    """
    Tell that given client is ready to supply given software release

    software_release -- URI of the software release
                        which has to be instantiated

    compute_node_guid -- the identifier of the compute_node inside the slapgrid
                     server.
    """


class slap(Interface):
  """
  Initialize slap connection to the slapgrid server

  Slapgrid server URL is defined during the slap library installation,
  as recipes should not use another server.
  """

  def initializeConnection(slapgrid_uri, authentification_key=None):
    """
    Initialize the connection parameters to the slapgrid servers.

    slapgrid_uri -- URI the slapgrid server connector

    authentification_key -- string the authenticate the agent. (Yes, there's a typo in the argument name)

    Example: https://slapos.server/slap_interface
    """

  def registerComputeNode(compute_node_guid):
    """
    Instantiate a compute_node in the slap library.

    compute_node_guid -- the identifier of the compute_node inside the slapgrid server.
    """

  def registerComputePartition(compute_node_guid, partition_id):
    """
    Instantiate a compute partition in the slap library.

    compute_node_guid -- the identifier of the compute_node inside the slapgrid server.

    partition_id -- the identifier of the compute partition inside the
                    slapgrid server.

    Raise an INotFoundError if compute_node_guid doesn't exist.
    """

  def registerSoftwareRelease(software_release):
    """
    Instantiate a software release in the slap library.

    software_release -- URI of the software release definition
    """

  def registerToken():
    """
    Instantiate an token in the slap library.
    """

  def registerOpenOrder():
    """
    Instantiate an open order in the slap library.
    """

  def registerSupply():
    """
    Instantiate a supply in the slap library.
    """

  def getSoftwareReleaseListFromSoftwareProduct(software_product_reference, software_release_url):
    """
    Get the list of Software Releases from a product or from another related
    Software Release, from a Software Product point of view.
    """

  def getOpenOrderDict():
    """
    Get the list of existing open orders (services) for the current user.
    """

  def getComputeNodeDict():
    """
    Get the list of existing compute_node for the current user.
    """
