<?php
/**
 * functions and class related to generating XML response file.
 *
 * Example: Normal response without error codes
 * $par_array = array("verb"=>"ListRecords","resumptionToken"=>"9CD1DA87F59C3E960871F4F3C9D093887C17D174");
 * $test = new ANDS_Response_XML($par_array);
 * $record_node = $test->create_record();
 * $test->create_header("function: identifier string",gmdate("Y-m-d\TH:i:s\Z"),"collection",$record_node);
 * $test->create_metadata($record_node);
 * $test->display();
 */

/**
 * A wraper of DOMDocument for data provider
 */
class ANDS_XML {
	
    public $doc; /**< Type: DOMDocument. Handle of current XML Document object */

    /**
     * Constructs an ANDS_XML object.
     *
     * @param $par_array Type: array.
     *   Array of request parameters for creating an ANDS_XML object.
     * \see create_request.
     */
    function __construct($par_array) {
        $this->doc = new DOMDocument("1.0","UTF-8");
        // oai_node equals to $this->doc->documentElement;
        $oai_node = $this->doc->createElement("OAI-PMH");
        $oai_node->setAttribute("xmlns","http://www.openarchives.org/OAI/2.0/");
        $oai_node->setAttribute("xmlns:xsi","http://www.w3.org/2001/XMLSchema-instance");
        $oai_node->setAttribute("xsi:schemaLocation","http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd");
        $this->addChild($oai_node,"responseDate",gmdate("Y-m-d\TH:i:s\Z"));
        $this->doc->appendChild($oai_node);
        $this->create_request($par_array);
    }

    /**
     * Add a child node to a parent node on a XML Doc: a worker function.
     *
     * @param $mom_node
     *   Type: DOMNode. The target node.
     *
     * @param $name
     *   Type: string. The name of child nade is being added
     *
     * @param $value
     *   Type: string. Text for the adding node if it is a text node.
     *
     * @return DOMElement $added_node
     *   The newly created node, can be used for further expansion.
     *   If no further expansion is expected, return value can be igored.
     */

    function addChild($mom_node,$name, $value='') {
        $added_node = $this->doc->createElement($name,$value);
        $added_node = $mom_node->appendChild($added_node);
        return $added_node;
    }

    /**
     * Create an OAI request node.
     *
     * @param $par_array Type: array
     *   The attributes of a request node. They describe the verb of the request and other associated parameters used in the request.
     * Keys of the array define attributes, and values are their content.
     */

    function create_request($par_array) {
        $request = $this->addChild($this->doc->documentElement,"request",MY_URI);
        foreach($par_array as $key => $value) {
            $request->setAttribute($key,$value);
        }
    }

    /**
     * Display a doc in a readable, well-formatted way for display or saving
     */
    function display() {
        $pr = new DOMDocument();
        $pr->preserveWhiteSpace = false;
        $pr->formatOutput = true;
        $pr->loadXML($this->doc->saveXML());
        echo $pr->saveXML();
    }
}

/**
 * Generate an XML response when a request cannot be finished
 *
 * It has only one derived member function
 */
class ANDS_Error_XML extends ANDS_XML {
    function __construct($par_array, $error_array) {
        parent::__construct($par_array);

        $oai_node = $this->doc->documentElement;
        foreach($error_array as $e) {
            list($code, $value) = explode("|", $e);
            $node = $this->addChild($oai_node,"error",$value);
            $node->setAttribute("code",$code);
        }
    }
}

/**
 * Generate an XML response to a request if no error has occured
 *
 * This is the class to further develop to suits a publication need
 */
class ANDS_Response_XML extends ANDS_XML {
    public $verbNode; /**< Type: DOMElement. Verb node itself. */
    protected $verb; /**< Type: string. The verb in the request */

    function __construct($par_array) {
        parent::__construct($par_array);
        $this->verb = $par_array["verb"];
        $this->verbNode = $this->addChild($this->doc->documentElement,$this->verb);
    }

    /** Add direct child nodes to verb node (OAI-PMH), e.g. response to ListMetadataFormats.
     * Different verbs can have different required child nodes.
     *  \see create_record, create_header
     * \see http://www.openarchives.org/OAI/2.0/openarchivesprotocol.htm.
     *
     * \param $nodeName Type: string. The name of appending node.
     * \param $value Type: string. The content of appending node.
     */
    function add2_verbNode($nodeName, $value=null) {
        return $this->addChild($this->verbNode,$nodeName,$value);
    }

    /**
     * Create an empty \<record\> node. Other nodes will be appended to it later.
     */
    function create_record() {
        return $this->add2_verbNode("record");
    }

    /** Headers are enclosed inside of \<record\> to the query of ListRecords, ListIdentifiers and etc.
     *
     * \param $identifier Type: string. The identifier string for node \<identifier\>.
     * \param $timestamp Type: timestamp. Timestapme in UTC format for node \<datastamp\>.
     * \param $ands_class Type: mix. Can be an array or just a string. Content of \<setSpec\>.
     * \param $add_to_node Type: DOMElement. Default value is null.
     * In normal cases, $add_to_node is the \<record\> node created previously. When it is null, the newly created header node is attatched to $this->verbNode.
     * Otherwise it will be attatched to the desired node defined in $add_to_node.
     */
    function create_header($identifier,$timestamp,$ands_class, $add_to_node=null) {
        if(is_null($add_to_node)) {
            $header_node = $this->add2_verbNode("header");
        } else {
            $header_node = $this->addChild($add_to_node,"header");
        }
        $this->addChild($header_node,"identifier",$identifier);
        $this->addChild($header_node,"datestamp",$timestamp);
        if (is_array($ands_class)) {
            foreach ($ands_class as $setspec) {
                $this->addChild($header_node,"setSpec",$setspec);
            }
        } else { $this->addChild($header_node,"setSpec",$ands_class); }
        return $header_node;
    }

    /** Create metadata node for holding metadata. This is always added to \<record\> node.
     *
     * \param $mom_record_node DOMElement. A node acts as the parent node.
     *
     * @return $meta_node Type: DOMElement.
     *   The newly created registryObject node which will be used for further expansion.
     *   metadata node itself is maintained by internally by the Class.
     */
    function create_metadata($mom_record_node) {
        $meta_node =  $this->addChild($mom_record_node,"metadata");
        return $meta_node;
    }

    /** If there are too many records request could not finished a resumpToken is generated to let harvester know
     *
     * \param $token Type: string. A random number created somewhere?
     * \param $expirationdatetime Type: string. A string representing time.
     * \param $num_rows Type: integer. Number of records retrieved.
     * \param $cursor Type: string. Cursor can be used for database to retrieve next time.
     */
    function create_resumpToken($token, $expirationdatetime, $num_rows, $cursor=null) {
        $resump_node = $this->addChild($this->verbNode,"resumptionToken",$token);
        if(isset($expirationdatetime)) {
            $resump_node->setAttribute("expirationDate",$expirationdatetime);
        }
        $resump_node->setAttribute("completeListSize",$num_rows);
        $resump_node->setAttribute("cursor",$cursor);
    }
}