<?php
/**
 * \file
 * \brief classes related to generating RIF-CS XML response file for ANDS.
 *
 *
 * Generate RIF-CS set records of Activity, Collection, Party.
 * - They are closely bounded to ANDS requirements, need to know the database for getting information.
 */

require_once('xml_creater.php');

/**
 * \brief For creating RIF-CS metadata to meet the requirement of ANDS.
 *
 * Class ANDS_RIFCS provides all essential functionalities for creating ANDS RIF-CS records.
 * The protected member functions are the backbone functions which can be used for creating any ANDS RIF-CS records.
 *
 */

class ANDS_RIFCS {
 /**
 	* \var $oai_pmh 
 	* Type: ANDS_Response_XML. Assigned by constructor. \see __construct
  */
	protected $oai_pmh;
	/** \var $working_node
	* Type: DOMElement. Assigned by constructor. \see __construct	
	*/
	protected $working_node;

	/**
	 * Constructor
	 *
	 * \param $ands_response_doc ANDS_Response_XML. A XML Doc acts as the parent node.
	 * \param $metadata_node DOMElement. The meta node which all subsequent nodes will be added to.
	 */
  function __construct($ands_response_doc, $metadata_node) {
		$this->oai_pmh = $ands_response_doc;
		$this->working_node = $metadata_node;
		$this->create_regObjects();
  }

  /**
   * A worker function for easily adding a newly created node to current XML Doc.
   * @param $mom_node Type: DOMElement. Node the new child will be attached to.
   * @param $name Type: sting. The name of the child node is being added.
   * @param $value Type: sting. The text content of the child node is being added. The default is ''.
   * @return DOMElement. The added child node
   */  
	protected function addChild($mom_node,$name, $value='') {
  	return $this->oai_pmh->addChild($mom_node,$name, $value); 
  }

	/** Create a registryObjects node to hold individual registryObject's.
	 *  This is only a holder node.
	*/
	protected 	function create_regObjects() {
		$this->working_node = $this->oai_pmh->addChild($this->working_node,'registryObjects');
		$this->working_node->setAttribute('xmlns',"http://ands.org.au/standards/rif-cs/registryObjects");
		$this->working_node->setAttribute('xmlns:xsi',"http://www.w3.org/2001/XMLSchema-instance");
		$this->working_node->setAttribute('xsi:schemaLocation','http://ands.org.au/standards/rif-cs/registryObjects http://services.ands.org.au/documentation/rifcs/1.2.0/schema/registryObjects.xsd');
	}
	
	/** Create a single registryObject node. Each set has its own structure but they all have an attribute of group, a key node and an originatingSource node. The newly created node will be used as the working node.
	 *
	 * \param $group string, group attribute of the new registryObject node .
	 * \param $key string, key node, used as an identifier.
	 * \param $originatingSource string, an url of the data provider.
	*/
	protected 	function create_regObject($group, $key, $originatingSource) {
		$regObj_node = $this->addChild($this->working_node,'registryObject');
		$regObj_node->setAttribute('group',$group);
		$this->addChild($regObj_node,'key',$key);
		$this->addChild($regObj_node,'originatingSource',$originatingSource);
		$this->working_node = $regObj_node;
	}
	
	/** RIF-CS node is the content node of RIF-CS metadata node which starts from regObjects.
	* Each set supportted in RIF-CS has its own content model. The created node will be used as the 
	* root node of this record for following nodes will be created.
	*
	* \param $set_name string, the name of set. For ANDS, they are Activity, Party and Collection
	* \param $set_type string, the type of set. For example, Activity can have project as a type.
	*/
	protected 	function create_rifcs_node($set_name, $set_type) {
		$this->working_node = $this->addChild($this->working_node, $set_name);
		$this->working_node->setAttribute('type', $set_type);
	}

   /**
   * Create a top level name node. 
   * @param $name_type string. Text for the types, can be either primary or abbreviated. Default: primary
   *
   * @return DOMElement $added_name_node.
   *   The newly created node, it will be used for further expansion by adding namePart.
   */
	protected 	function create_name_node($name_type = 'primary') {
		$c = $this->addChild($this->working_node, 'name');
		$c->setAttribute('type', $name_type);
		return $c;
	}
	
   /**
   * Create a namePart of a name node. 
   * @param $name_node
   *   Type: DOMElement. Node of name_node created previously
   *
   * @param $value
   *   Type: string. Text fror this namePart
   *
   * @param $part_type Type: string, used for group:person record. Types can be: titile, given, family
   *
   */
	protected 	function create_namePart($name_node, $value, $part_type = '') {
		$c = $this->addChild($name_node, 'namePart', $value);
		if (!empty($part_type)) {
			$c->setAttribute('type', $part_type);
		}
	}
	
	/** Create related object. One RIF-CS can have more than one related object nodes,
	 * each object is described by one node.
	 * \param $key
	 *	 Type: string. The identifier of the related object.
	 * \param $relation_type
	 *	 Type: string. Type of relationship.
	 * 
	*/
	protected 	function create_relatedObject($key,$relation_type) {
		$c = $this->addChild($this->working_node, 'relatedObject');
		$this->addChild($c,'key',$key);
		$c = $this->addChild($c, 'relation');
		// Mimick ANDS with enpty value to get both tags for relation. Only for better display
		// $c = $this->addChild($c, 'relation','     ');
		$c->setAttribute('type', $relation_type);
	}
	
	/** Create description node. One RIF-CS can have more than one description nodes.
	 * Each description node has only one description.
	 * \param $value Type: string. The content of the description.
	 * \param $des_type Type: string. Type of the description. Types can be brief, full, acessRights and note. Default is 'brief'. 
	*/
	protected 	function create_description_node($value, $des_type='brief') {
		$c = $this->addChild($this->working_node, 'description', $value);
		$c->setAttribute('type', $des_type);
	}

	/** Create local or other type of identifier inside of RIF-CS metadata node
	 * \param $key
	 *	Type string. The indentifier itself.
	 * \param $i_type
	 *	Type string. Type of identifier. Can be abn, uri, local, etc.. Default is local. 
	*/
	protected 	function create_identifier_node($key, $i_type='local') {
		$c = $this->addChild($this->working_node, 'identifier',$key);
		$c->setAttribute('type', $i_type);
	}
	
	/** Location node is a holder node for either address or spatial nodes
	 * \return DOMElement node, for adding address or spatial nodes.
	*/
	protected 	function create_location_node() {
		return $this->addChild($this->working_node, 'location');
	}
	
	/** Address node is a holder node for phiscal or electrical nodes.
	 * \param $location_node Type: DOMElement. Location node created previously.
	 * \return DOMElement
	*/
	protected 	function create_address_node($location_node) {
		return $this->addChild($location_node, 'address');
	}
	
	/** Electrical address node.	Used for email, url, etc
	 * \param $addr_node Type: DOMElement. Previously created address node.
	 * \param $e_node Type: string. The content of the adding node.
	 * \param $e_type Type: string. Default is email.
	*/
	protected 	function create_e_node($addr_node, $e_node, $e_type = 'email') {
		$c = $this->addChild($addr_node, 'electronic');
		$c->setAttribute('type', $e_type);
		$this->addChild($c,'value',$e_node);
	}

	/** Physical node is a holder node for phone or fax nodes.
	 * \param $addr_node Type: DOMelement. Address node created before to which the new phiscial->addressPart will be attached.
	 * \param $number Type: string. Telephone or fax number as a string.
	 * \param $fone_fax Type: string. Either telehoneNumber or faxNumber.
	*/
	protected 	function create_physcial_fone_fax($addr_node, $number,$fone_fax='telephoneNumber') {
		$c = $this->addChild($addr_node, 'physical');
		$c = $this->addChild($c, 'addressPart', $number);
		$c->setAttribute('type', $fone_fax);		
	}

	/** create address node under location node, either streetAddress or postalAddress.
	 * But they are in text (one block) format.
	 * \param $addr_node Type: DOMelement. Address node created before to which the new phiscial->addressPart will be attached.
	 * \param $txt_addr string, full street address in text block format
	 * \param $phys_type string, default is 'streetAddress', can be 'postalAddress'
	*/
	protected 	function create_physcial_addr_txt($addr_node, $txt_addr,$phys_type='streetAddress') {
		$c = $this->addChild($addr_node, 'physical');
		$c->setAttribute('type', $phys_type);
		$c = $this->addChild($c, 'addressPart', $txt_addr);
		$c->setAttribute('type', 'text');		
	}

	/** Create spatial node under a location node.
	 * \param $location_node Type: DOMElement. Location node where spatial node is being added to.
	 * \param $value Type: string. The value of spatial information. Default is local latitude and longitude.
	 * \param $sp_type Type: string. Type of spaitial informaion. Default is kmlPolyCoords.
	*/
	protected 	function create_spatial_node($location_node, $value = '138.6396,-34.97063', $sp_type = 'kmlPolyCoords') {
		$c = $this->addChild($location_node, 'spatial',$value);
		$c->setAttribute('type',$sp_type);
	}

	/** Create temporal coverage node for collection or activity records.
	 * \param $values Type: 2-D array. The values of temporal coverage. It can has maximal two elements: one from 'dateFrom' and another for 'dateTo'.
	 * Either can be ommited according to RIF-CS schema. Each element of $values is an array and has keys: date, type and format.
	 * ['date'] is a string represents date. It has to be in W3CDTF or UTC format.
	 * ['type'] has to be either 'dateFrom' or 'dateTo'. 
	 * ['format'] is optional and its default is 'W3CDTF'. UTC format requires date has to be in UTC: dateTtimeZ.
	 * It throws an exception if the input parameter is not an array.
	 */
	protected 	function create_coverage_tempo($values) {
		// Non array is not acceptable.
		if (!is_array($values)) { throw new Exception('The input of temporal coverage has to be an array of arraies with keys.');}
		$c = $this->addChild($this->working_node,'coverage');
		$t = $this->addChild($c,'temporal');
		foreach($values as $value) $this->create_coverage_tempo_date($t, $value);
	}

	/** Create temporal coverage node for collection or activity records.
	 * \param $t Type: DOMElement. The \<coverage\>\<temporal/\>\</coverage\> node to which \<date\> nodes will be attached to.
	 * \param $value Type: array. The value of temporal coverage. It has maxmimal three elements with keys: type, date and format.
	 * It throws an exception if the input parameter is not an array.
	 * \see create_coverage_tempo
	 */
	private function create_coverage_tempo_date($t, $value) {
		if (!is_array($value)) { throw new Exception('The input of temporal coverage has to be an array with keys.');}
		$d = $this->addChild($t,'date',$value['date']);
		$d->setAttribute('type',$value['type']);
		if (isset($value['format'])) $d->setAttribute('dateFormat',$value['format']);
		else $d->setAttribute('dateFormat','W3CDTF');
	}
	
	/** Create a subject node for a researcher, project, project, etc
	 * \param $value Type: string. A string representing the new namePart.
	 * \param $subject_type Type: string. A string representing the type of subject. The default value is anzsrc-for.
	*/
	protected function create_subject_node($value, $subject_type = 'anzsrc-for') {
		if (empty($value)) return;
		$c = $this->addChild($this->working_node,'subject',$value);
		$c->setAttribute('type',$subject_type);
	}
} // end of class ANDS_RIFCS