<?php
/**
 * This file is part of the set of the DDR Simple API definition. It contains the
 * definition of the {@link ServiceFactory} interface.
 * 
 * @author lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package AskPythia
 * @subpackage Interface
 * @version $Revision: 1.8 $
 * @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 Service} interface definition as the factory creates
 * instances of that class.
 */
require_once(dirname(__FILE__) . '/service.php');

/**
 * {@link http://www.w3.org/TR/DDR-Simple-API/#sec-ServiceFactory ServiceFactory}
 * class as defined in the {@link http://www.w3.org/TR/DDR-Simple-API/
 * DDR Simple API} standard.
 * 
 * The factory is used to instantiate a {@link Service} with the supplied 
 * default namespace and configuration.
 * 
 * The factory expects implementations of the {@link Service} interface of the
 * DDR Simple API to be "[impl]Service" where [impl] is the implementation name
 * given to the {@link newService()} method. For instance, when called with a
 * "WURFL" argument, the method will create an instance of the "WURFLService"
 * class.
 * 
 * The {@link newService()} method tries to include the:
 *   "../[impl]/[impl]Service.php
 * that could contain the implementation of the [impl]_Service class before it
 * attempts to create the object. It does not fail if the file does not exist
 * (it does fail when the class does not exist, though).
 * 
 * @author 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.8 $
 * @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)
 */
class ServiceFactory {
	/**
	 * Instantiates an instance of the class $clazz establishing the Default
	 * Vocabulary to be the one specified and with the possibility to provide
	 * implementation specific parameters in the $configuration parameter.
	 *
	 * See the description of the {@link ServiceFactory} class above for more
	 * details on the naming rule implementations of the {@link Service}
	 * interface must follow for instantiation to succeed.
	 * 
	 * A call to {@link Service::initialize()} is issued prior to returning the
	 * created instance. 
	 * 
	 * @param string $clazz the implementation name
	 * @param string $defaultVocabulary the URI of the default vocabulary to use
	 * @param mixed $configuration implementation-specific configuration settings 
	 * @return Service a new instance of the $clazz_Service class
	 * @exception 
	 */
	public static function newService($clazz, $defaultVocabulary, $configuration) {
		$filename = dirname(__FILE__) . '/../implementation/' . $clazz . '/' . $clazz . 'Service.php';
		if (file_exists($filename)) {
			include_once($filename);			
		}
		$serviceClass = $clazz.'Service';
		$result = new $serviceClass();
		$result->initialize($defaultVocabulary, $configuration);
		return $result;
	}
}

?>