MetaDataStorageHandler: Changed to support chaining of metadata sources.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@346 44740490-163a-0410-bde0-09ae8108e29a

1 files changed, 144 insertions, 89 deletions

diff --git a/lib/SimpleSAML/Metadata/MetaDataStorageHandler.php b/lib/SimpleSAML/Metadata/MetaDataStorageHandler.php
index 001aecd..03074e5 100644
--- a/lib/SimpleSAML/Metadata/MetaDataStorageHandler.php
+++ b/lib/SimpleSAML/Metadata/MetaDataStorageHandler.php
@@ -1,107 +1,95 @@
 <?php
 
 require_once('SimpleSAML/Configuration.php');
-require_once('SimpleSAML/Utilities.php');
+require_once('SimpleSAML/Metadata/MetaDataStorageSource.php');
 
 /**
- * This file defines a base class for metadata handling.
- * Instantiation of session handler objects should be done through
- * the class method getMetadataHandler().
+ * This file defines a class for metadata handling.
  *
  * @author Andreas Åkre Solberg, UNINETT AS. <andreas.solberg@uninett.no>
  * @package simpleSAMLphp
  * @version $Id$
  */ 
-abstract class SimpleSAML_Metadata_MetaDataStorageHandler {
+class SimpleSAML_Metadata_MetaDataStorageHandler {
 
 
-	protected $metadata = null;
-	protected $hostmap = null;
-
-
-	/* This static variable contains a reference to the current
+	/**
+	 * This static variable contains a reference to the current
 	 * instance of the metadata handler. This variable will be NULL if
 	 * we haven't instantiated a metadata handler yet.
 	 */
 	private static $metadataHandler = NULL;
 
 
+	/**
+	 * This is a list of all the metadata sources we have in our metadata
+	 * chain. When we need metadata, we will look through this chain from start to end.
+	 */
+	private $sources;
 
-	/* This function retrieves the current instance of the metadata handler.
+
+	/**
+	 * This function retrieves the current instance of the metadata handler.
 	 * The metadata handler will be instantiated if this is the first call
 	 * to this fuunction.
 	 *
-	 * Returns:
-	 *  The current metadata handler.
+	 * @return The current metadata handler instance.
 	 */
 	public static function getMetadataHandler() {
 		if(self::$metadataHandler === NULL) {
-			self::createMetadataHandler();
+			self::$metadataHandler = new SimpleSAML_Metadata_MetaDataStorageHandler();
 		}
 
 		return self::$metadataHandler;
 	}
 
 
-
-	/* This constructor is included in case it is needed in the the
-	 * future. Including it now allows us to write parent::__construct() in
-	 * the subclasses of this class.
+	/**
+	 * This constructor initializes this metadata storage handler. It will load and
+	 * parse the configuration, and initialize the metadata source list.
 	 */
 	protected function __construct() {
-		
-	}
-
 
-	/* This function creates an instance of the metadata handler which is
-	 * selected in the 'metadata.handler' configuration directive. If no
-	 * metadata handler is selected, then we will fall back to the default
-	 * PHP metadata handler.
-	 */
-	public static function createMetadataHandler() {
-	
-		/* Get the configuration. */
 		$config = SimpleSAML_Configuration::getInstance();
-		assert($config instanceof SimpleSAML_Configuration);
 
-		/* Get the metadata handler option from the configuration. */
-		$handler = $config->getValue('metadata.handler');
+		$sourcesConfig = $config->getValue('metadata.sources', NULL);
 
-		/* If 'session.handler' is NULL or unset, then we want
-		 * to fall back to the default PHP session handler.
-		 */
-		if(is_null($handler)) {
-			$handler = 'flatfile';
+		/* For backwards compatibility, and to provide a default configuration. */
+		if($sourcesConfig === NULL) {
+			$type = $config->getValue('metadata.handler', 'flatfile');
+			$sourcesConfig = array(array('type' => $type));
 		}
 
-
-		/* The session handler must be a string. */
-		if(!is_string($handler)) {
-			throw new Exception('Invalid setting for the [metadata.handler] configuration option. This option should be set to a valid string.');
+		if(!is_array($sourcesConfig)) {
+			throw new Exception(
+				'Invalid configuration of the \'metadata.sources\' configuration option.' .
+				' This option should be an array.'
+				);
 		}
 
-		$handler = strtolower($handler);
-
-		if($handler === 'flatfile') {
+		$this->sources = array();
 		
-			require_once('SimpleSAML/Metadata/MetaDataStorageHandlerFlatfile.php');
-			$sh = new SimpleSAML_Metadata_MetaDataStorageHandlerFlatfile();
-			
-		} elseif ($handler === 'saml2xmlmeta')  {
-
-			require_once('SimpleSAML/Metadata/MetaDataStorageHandlerSAML2Meta.php');
-			$sh = new SimpleSAML_Metadata_MetaDataStorageHandlerSAML2Meta();
+		foreach($sourcesConfig as $elementConfig) {
+			if(!is_array($elementConfig)) {
+				throw new Exception(
+					'Invalid configuration of the \'metadata.sources\' configuration option.' .
+					' Every element in the array should be an associative array.'
+					);
+			}
 
-		
-		} else {
-			throw new Exception('Invalid value for the [metadata.handler] configuration option. Unknown handler: ' . $handler);
+			$src = SimpleSAML_Metadata_MetaDataStorageSource::getSource($elementConfig);
+			$this->sources[] = $src;
 		}
-		
-		/* Set the session handler. */
-		self::$metadataHandler = $sh;
 	}
-	
-	
+
+
+	/**
+	 * This function is used to generate some metadata elements automatically.
+	 *
+	 * @param $property  The metadata property which should be autogenerated.
+	 * @param $set  The set we the property comes from.
+	 * @return The autogenerated metadata property.
+	 */
 	public function getGenerated($property, $set = 'saml20-sp-hosted') {
 		
 		/* Get the configuration. */
@@ -146,49 +134,116 @@ abstract class SimpleSAML_Metadata_MetaDataStorageHandler {
 		
 		throw new Exception('Could not generate metadata property ' . $property . ' for set ' . $set . '.');
 	}
-	
+
+
+	/**
+	 * This function lists all known metadata in the given set. It is returned as an associative array
+	 * where the key is the entity id.
+	 *
+	 * @param $set  The set we want to list metadata from.
+	 * @return An associative array with the metadata from from the given set.
+	 */
 	public function getList($set = 'saml20-idp-remote') {
-		if (!isset($this->metadata[$set])) {
-			$this->load($set);
+
+		assert('is_string($set)');
+
+		$result = array();
+
+		foreach($this->sources as $source) {
+			$srcList = $source->getMetadataSet($set);
+
+			/* $result is the last argument to array_merge because we want the content already
+			 * in $result to have precedence.
+			 */
+			$result = array_merge($srcList, $result);
 		}
-		return $this->metadata[$set];
+
+		return $result;
 	}
-	
+
+
+	/**
+	 * This function retrieves metadata for the current entity based on the hostname/path the request
+	 * was directed to. It will throw an exception if it is unable to locate the metadata.
+	 *
+	 * @param $set  The set we want metadata from.
+	 * @return An associative array with the metadata.
+	 */
 	public function getMetaDataCurrent($set = 'saml20-sp-hosted') {
-		return $this->getMetaData($this->getMetaDataCurrentEntityID($set), $set);
+		return $this->getMetaData(NULL, $set);
 	}
-	
+
+
+	/**
+	 * This function locates the current entity id based on the hostname/path combination the user accessed.
+	 * It will throw an exception if it is unable to locate the entity id.
+	 *
+	 * @param $set  The set we look for the entity id in.
+	 * @return The entity id which is associated with the current hostname/path combination.
+	 */
 	public function getMetaDataCurrentEntityID($set = 'saml20-sp-hosted') {
+
+		assert('is_string($set)');
+
+		/* First we look for the hostname/path combination. */
+		$currenthostwithpath = SimpleSAML_Utilities::getSelfHostWithPath(); // sp.example.org/university
+
+		foreach($this->sources as $source) {
+			$entityId = $source->getEntityIdFromHostPath($currenthostwithpath, $set);
+			if($entityId !== NULL) {
+				return $entityId;
+			}
+		}
+
 	
-		if (!isset($this->metadata[$set])) {
-			$this->load($set);
+		/* Then we look for the hostname. */
+		$currenthost = SimpleSAML_Utilities::getSelfHost(); // sp.example.org
+		if(strpos($currenthost, ":") !== FALSE) {
+			$currenthostdecomposed = explode(":", $currenthost);
+			$currenthost = $currenthostdecomposed[0];
 		}
-		$currenthost         = SimpleSAML_Utilities::getSelfHost(); 			// sp.example.org
-		$currenthostwithpath = SimpleSAML_Utilities::getSelfHostWithPath(); 	// sp.example.org/university
-		
-		if(strstr($currenthost, ":")) {
-				$currenthostdecomposed = explode(":", $currenthost);
-				$currenthost = $currenthostdecomposed[0];
+
+		foreach($this->sources as $source) {
+			$entityId = $source->getEntityIdFromHostPath($currenthost, $set);
+			if($entityId !== NULL) {
+				return $entityId;
+			}
 		}
-		
-		if (!isset($this->hostmap[$set])) {
-			throw new Exception('No default entities defined for metadata set [' . $set . '] (host:' . $currenthost. ')');
+
+
+		/* We were unable to find the hostname/path in any metadata source. */
+		throw new Exception('Could not find any default metadata entities in set [' . $set . '] for host [' . $currenthost . ' : ' . $currenthostwithpath . ']');
+	}
+
+
+	/**
+	 * This function looks up the metadata for the given entity id in the given set. It will throw an
+	 * exception if it is unable to locate the metadata.
+	 *
+	 * @param $entityId  The entity id we are looking up. This parameter may be NULL, in which case we look up
+	 *                   the current entity id based on the current hostname/path.
+	 * @param $set  The set of metadata we are looking up the entity id in.
+	 */
+	public function getMetaData($entityId, $set = 'saml20-sp-hosted') {
+
+		assert('is_string($set)');
+
+		if($entityId === NULL) {
+			$entityId = $this->getMetaDataCurrentEntityID($set);
 		}
-		if (!isset($currenthost)) {
-			throw new Exception('Could not get HTTP_HOST, in order to resolve default entity ID');
+
+		assert('is_string($entityId)');
+
+		foreach($this->sources as $source) {
+			$metadata = $source->getMetaData($entityId, $set);
+			if($metadata !== NULL) {
+				return $metadata;
+			}
 		}
-		
-		
-		if (isset($this->hostmap[$set][$currenthostwithpath])) return $this->hostmap[$set][$currenthostwithpath];
-		if (isset($this->hostmap[$set][$currenthost])) return $this->hostmap[$set][$currenthost];
-		
-		throw new Exception('Could not find any default metadata entities in set [' . $set . '] for host [' . $currenthost . ' : ' . $currenthostwithpath . ']');
+
+		throw new Exception('Unable to locate metadata for \'' . $entityId . '\' in set \'' . $set . '\'.');
 	}
 
-	abstract public function load($set);
-	abstract public function getMetaData($entityid = null, $set = 'saml20-sp-hosted');
-	
-	
 }
 
 ?>
\ No newline at end of file