<?php
/**
 * This file is part of the set of the DDR Simple API definition. It contains the
 * definition of the {@link Service} interface.
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package AskPythia
 * @subpackage Interface
 * @version $Revision: 1.13 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */

/**
 * Include the {@link Evidence} interface definition as
 * {@link newHTTPEvidence()} methods create instances of a class that
 * implement that interface.
 */
require_once(dirname(__FILE__)."/evidence.php");
/**
 * Include the {@link PropertyName} interface definition as
 * {@link newPropertyName()} methods create instances of a class that
 * implement that interface.
 */
require_once(dirname(__FILE__)."/propertyName.php");
/**
 * Include the {@link PropertyRef} interface definition as
 * {@link newPropertyRef()} methods create instances of a class that
 * implement that interface.
 */
require_once(dirname(__FILE__)."/propertyRef.php");
/**
 * Include the {@link PropertyValue} interface definition as
 * {@link getPropertyValue()} methods create instances of a class that
 * implement that interface.
 */
require_once(dirname(__FILE__)."/propertyValue.php");
/**
 * Include the {@link PropertyValues} interface definition as
 * {@link getPropertyValues()} methods create instances of a class that
 * implement that interface.
 */
require_once(dirname(__FILE__)."/propertyValues.php");

/**
 * {@link http://www.w3.org/TR/DDR-Simple-API/#sec-Service Service} interface
 * as defined in the {@link http://www.w3.org/TR/DDR-Simple-API/ DDR Simple API}
 * standard.
 * 
 * The Service interface is the core of the DDR Simple API. Using methods of
 * Service the caller supplies {@link Evidence} representing the Delivery
 * Context and an indication of the properties of interest. The methods return 
 * {@link PropertyValue} objects extracted from some underlying DDR based on the
 * Evidence. The list of PropertyValue can then be queried to reveal the values
 * of the Properties of interest.
 *
 * Service objects are typically instantiated through a call to
 * {@link ServiceFactory::newService()}, which invokes the {@link initialize()}
 * method to set the default vocabulary and other implementation specific settings.  
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package AskPythia
 * @subpackage Interface
 * @link http://www.w3.org/TR/DDR-Simple-API/ Device Description Repository Simple API
 * @version $Revision: 1.13 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */
interface Service {
	/**
	 * Creates an empty HTTP Evidence.
	 * 
	 * @return Evidence an empty HTTP Evidence.
	 */	
	public function newHTTPEvidence();
	
	/**
	 * Creates an HTTP Evidence from a list of HTTP header names and values.
	 * 
	 * @param array(string=>string) $map the HTTP header names and values.
	 * @return Evidence an HTTP Evidence.
	 */
	public function newHTTPEvidenceM($map);
	
	/**
	 * Creates a property using the default vocabulary.
	 * 
	 * @param string $localPropertyName the local property name (no namespace).
	 * @return PropertyName a property initialized with the given name and the default vocabulary.
	 * @exception NameException the property is not supported.
	 */
	public function newPropertyNameS($localPropertyName);
	
	/**
	 * Creates a property using the specified vocabulary.
	 * 
	 * @param string $localPropertyName the property name as a string value.
	 * @param string $vocabularyIRI the IRI of the vocabulary to use.
	 * @return PropertyName a property initialized with the given name and vocabulary.
	 * @exception NameException the property is not supported.
	 */
	public function newPropertyNameSS($localPropertyName, $vocabularyIRI);
	
	/**
	 * Creates a property reference using given local name, the default vocabulary
	 * and the default aspect associated with the property.
	 * 
	 * @param string $localPropertyName the local property name (no namespace).
	 * @return PropertyRef a property reference initialized with the given name,
	 *         the default vocabulary and the default aspect for that property
	 * @exception NameException the property is not supported.
	 */
	public function newPropertyRefS($localPropertyName);
	
	/**
	 * Creates a property reference using the given property and the default
	 * aspect associated with the property.
	 * 
	 * @param PropertyName $propertyName the property to use.
	 * @return PropertyRef a property reference initialized with the given
	 *         property and its default aspect.
	 * @exception NameException the property is not supported.
	 */
	public function newPropertyRefPn($propertyName);
	
	/**
	 * Creates a property reference using the given property and aspect.
	 * 
	 * @param PropertyName $propertyName the property to use.
	 * @param string $localAspectName the aspect name of the property.
	 * @return PropertyRef a property reference initialized with the given
	 *         property and aspect.
	 * @exception NameException the property is not supported.
	 */
	public function newPropertyRefPnS($propertyName, $localAspectName);
	
	/**
	 * Returns all property values that match the device identified
	 * by the given evidence.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @return PropertyValues all the property values that match the identified device.
	 * @exception NameException the property is not supported.
	 */
	public function getPropertyValuesE($evidence);
	
	/**
	 * Returns all property values that match the device identified
	 * by the given evidence and that apply to the given aspect name
	 * in the default vocabulary.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param string $localAspectName the aspect name to search for in the set.
	 * @return PropertyValues all the property values that match the identified device
	 *         and the given aspect in the default vocabulary.
	 * @exception NameException the property is not supported.
	 */
	public function getPropertyValuesES($evidence, $localAspectName);
	
	/**
	 * Returns all property values that match the device identified
	 * by the given evidence and that apply to the given aspect name
	 * in the given vocabulary.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param string $localAspectName the aspect name to search for in the set.
	 * @param $vocabularyIRI the IRI of the vocabulary the aspect belongs to.
	 * @return PropertyValues all the property values that match the identified device
	 *         and the given aspect in the given vocabulary.
	 * @exception NameException the property is not supported.
	 */
	public function getPropertyValuesESS($evidence, $localAspectName, $vocabularyIRI);
	
	/**
	 * Returns all property values that match the device identified
	 * by the given evidence and that are in the given set of properties.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param array(PropertyRef) $propertyRefs the list of properties to search for.
	 * @return PropertyValues all the property values that match the identified device
	 *         and that are part of the given set of properties.
	 * @exception NameException at least one of the properties is not supported.
	 */
	public function getPropertyValuesEPr($evidence, $propertyRefs);
	
	/**
	 * Returns the requested property value for the device identified by the given
	 * evidence.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param PropertyRef $propertyRef the property to retrieve.
	 * @return PropertyValue the requested property value.
	 * @exception NameException the property is not supported.
	 */	
	public function getPropertyValueEPr($evidence, $propertyRef);
	
	/**
	 * Returns the requested property value for the device identified by the given
	 * evidence. The property is understood as applying to the default aspect.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param PropertyName $propertyName the property to retrieve. 
	 * @return PropertyValue the requested property value.
	 * @exception NameException the property is not supported.
	 */	
	public function getPropertyValueEPn($evidence, $propertyName);
	
	/**
	 * Returns the requested property value for the device identified by the given
	 * evidence. The property is searched for in the default vocabulary and
	 * understood as applying to the default aspect.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param string $localPropertyName the local property name (no namespace).
	 * @return PropertyValue the requested property value.
	 * @exception NameException the property is not supported.
	 */	
	
	public function getPropertyValueES($evidence, $localPropertyName);
	
	/**
	 * Returns the requested property value for the device identified by the given
	 * evidence. The property is searched for in the given vocabulary and aspect.
	 * 
	 * @param Evidence $evidence Evidence to use to identify the device in the DDR.
	 * @param string $localPropertyName the local property name (no namespace).
	 * @param string $localAspectName the aspect name the property applies to (no namespace).
	 * @param string $vocabularyIRI the IRI of the vocabulary to search for the property.
	 * @return PropertyValue the requested property value.
	 * @exception NameException the property is not supported.
	 */	
	public function getPropertyValueESSS($evidence, $localPropertyName, $localAspectName, $vocabularyIRI);
	
	/**
	 * Returns information about the implementation of the API including the current version.
	 * 
	 * @return string implementation version information for diagnostic purpose.
	 */
	public function getImplementationVersion();
	
	/**
	 * Returns information about the underlying data (values for Properties) if the 
	 * implementation has a versioning system for that information.
	 * 
	 * The value "__NOT_SUPPORTED" must be returned when the implementation has no 
	 * versioning system for that information.
	 * 
	 * @return string version information about the data of the DDR.
	 */
	public function getDataVersion();
	
	/**
	 * Lists the combination of all known Properties and Aspects in all
	 * Vocabularies that can be used (without causing a NameException to be
	 * thrown).
	 * 
	 * The order in which Properties are listed is not significant.
	 * 
	 * @return array(PropertyRef) the list of property references that may be used.
	 */
	public function listPropertyRefs();
	
	/**
	 * Initialize the Service instance.
	 * 
	 * The method is called automatically by the {@link ServiceFactory::newService()}
	 * method.
	 * 
	 * @param string $defaultVocabularyIRI the default vocabulary to use.
	 * @param mixed $props implementation-specific properties.
	 * @exception NameException the given vocabulary is not supported.
	 * @exception InitializationException there was a problem during initialization.
	 */
	public function initialize($defaultVocabularyIRI, $props);
}

?>