芝麻web文件管理V1.00

编辑当前文件:/home/strato/chroot/opt/RZphp74/includes/XML/Query2XML.php

<?php
/**
 * This file contains the class XML_Query2XML and all exception classes.
 *
 * PHP version 5
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @copyright 2006 Lukas Feiler
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @version CVS: $Id: Query2XML.php 309897 2011-04-02 17:36:42Z lukasfeiler $
 * @link http://pear.php.net/package/XML_Query2XML
 */

/**
 * PEAR_Exception is used as the parent for XML_Query2XML_Exception.
 */
require_once 'PEAR/Exception.php';

/**
 * Create XML data from SQL queries.
 *
 * XML_Query2XML heavily uses exceptions and therefore requires PHP5.
 * Additionally one of the following database abstraction layers is
 * required: PDO (compiled-in by default since PHP 5.1), PEAR DB,
 * PEAR MDB2, ADOdb.
 *
 * The two most important public methods this class provides are:
 *
 * {@link XML_Query2XML::getFlatXML()}
 * Transforms your SQL query into flat XML data.
 *
 * {@link XML_Query2XML::getXML()}
 * Very powerful and flexible method that can produce whatever XML data you want. It
 * was specifically written to also handle LEFT JOINS.
 *
 * They both return an instance of the class DOMDocument provided by PHP5's
 * built-in DOM API.
 *
 * A typical usage of XML_Query2XML looks like this:
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * $query2xml = XML_Query2XML::factory(MDB2::factory($dsn));
 * $dom = $query2xml->getXML($sql, $options);
 * header('Content-Type: application/xml');
 * print $dom->saveXML();
 * ?>
 * </code>
 *
 * Please read the {@tutorial XML_Query2XML.pkg tutorial} for
 * detailed usage examples and more documentation.
 * 
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @copyright 2006 Lukas Feiler
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @version Release: 1.7.2
 * @link http://pear.php.net/package/XML_Query2XML
 */
class XML_Query2XML
{
 /**
 * Primary driver.
 * @var XML_Query2XML_Driver A subclass of XML_Query2XML_Driver.
 */
 private $_driver;
 
 /**
 * An instance of PEAR Log
 * @var mixed An object that has a method with the signature log(String $msg);
 * preferably PEAR Log.
 * @see enableDebugLog
 * @see disableDebugLog
 */
 private $_debugLogger;
 
 /**
 * Whether debug logging is to be performed
 * @var boolean
 * @see enableDebugLog
 * @see disableDebugLog
 */
 private $_debug = false;
 
 /**
 * Whether profiling is to be performed
 * @var boolean
 * @see startProfiling()
 * @see stopProfiling()
 */
 private $_profiling = false;
 
 /**
 * The profiling data.
 * @var array A multi dimensional associative array
 * @see startProfiling()
 * @see stopProfiling()
 * @see _debugStartQuery()
 * @see _debugStopQuery()
 * @see _stopDBProfiling()
 */
 private $_profile = array();
 
 /**
 * An associative array of global options.
 * @var array An associative array
 * @see setGlobalOption()
 */
 private $_globalOptions = array(
 'hidden_container_prefix' => '__'
 );
 
 /**
 * An associative array that will contain an element for each prefix.
 * The prefix is used as the element key. Each array element consists
 * of an indexed array containing a file path and a class name.
 * @var array An associative multidimensional array.
 * @see registerPrefix()
 * @see unregisterPrefix()
 * @see unregisterAllPrefixes()
 * @see _buildCommandChain()
 */
 private $_prefixes = array(
 '?' => array(
 'XML/Query2XML/Data/Condition/NonEmpty.php',
 'XML_Query2XML_Data_Condition_NonEmpty'
 ),
 '&' => array(
 'XML/Query2XML/Data/Processor/Unserialize.php',
 'XML_Query2XML_Data_Processor_Unserialize'
 ),
 '=' => array(
 'XML/Query2XML/Data/Processor/CDATA.php',
 'XML_Query2XML_Data_Processor_CDATA'
 ),
 '^' => array(
 'XML/Query2XML/Data/Processor/Base64.php',
 'XML_Query2XML_Data_Processor_Base64'
 ),
 ':' => array(
 'XML/Query2XML/Data/Source/Static.php',
 'XML_Query2XML_Data_Source_Static'
 ),
 '#' => array(
 'XML/Query2XML/Data/Source/PHPCallback.php',
 'XML_Query2XML_Data_Source_PHPCallback'
 ),
 '~' => array(
 'XML/Query2XML/Data/Source/XPath.php',
 'XML_Query2XML_Data_Source_XPath'
 )
 );
 
 /**
 * Constructor
 *
 * @param mixed $backend A subclass of XML_Query2XML_Driver or
 * an instance of PEAR DB, PEAR MDB2, ADOdb,
 * PDO, Net_LDAP2 or Net_LDAP.
 */
 private function __construct($backend)
 {
 if ($backend instanceof XML_Query2XML_Driver) {
 $this->_driver = $backend;
 } else {
 $this->_driver = XML_Query2XML_Driver::factory($backend);
 }
 }
 
 /**
 * Factory method.
 * As first argument pass an instance of PDO, PEAR DB, PEAR MDB2, ADOdb,
 * Net_LDAP or an instance of any class that extends XML_Query2XML_Driver:
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * $query2xml = XML_Query2XML::factory(
 * new PDO('mysql://root@localhost/Query2XML_Tests')
 * );
 * ?>
 * </code>
 *
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * require_once 'DB.php';
 * $query2xml = XML_Query2XML::factory(
 * DB::connect('mysql://root@localhost/Query2XML_Tests')
 * );
 * ?>
 * </code>
 * 
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * require_once 'MDB2.php';
 * $query2xml = XML_Query2XML::factory(
 * MDB2::factory('mysql://root@localhost/Query2XML_Tests')
 * );
 * ?>
 * </code>
 * 
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * require_once 'adodb/adodb.inc.php';
 * $adodb = ADONewConnection('mysql');
 * $adodb->Connect('localhost', 'root', '', 'Query2XML_Tests');
 * $query2xml = XML_Query2XML::factory($adodb);
 * ?>
 * </code>
 *
 * @param mixed $backend An instance of PEAR DB, PEAR MDB2, ADOdb, PDO,
 * Net_LDAP or a subclass of XML_Query2XML_Driver.
 *
 * @return XML_Query2XML A new instance of XML_Query2XML
 * @throws XML_Query2XML_DriverException If $backend already is a PEAR_Error.
 * @throws XML_Query2XML_ConfigException If $backend is not an instance of a
 * child class of DB_common, MDB2_Driver_Common, ADOConnection
 * PDO, Net_LDAP or XML_Query2XML_Driver.
 */
 public static function factory($backend)
 {
 return new XML_Query2XML($backend);
 }
 
 /**
 * Register a prefix that can be used in all value specifications.
 *
 * @param string $prefix The prefix name. This must be a single chracter.
 * @param string $className The name of the Data Class. This class has
 * to extend XML_Query2XML_Data.
 * @param string $filePath The path to the file that contains the Command
 * class. This argument is optional.
 *
 * @return void
 * @throws XML_Query2XML_ConfigException Thrown if $prefix is not a string
 * or has a length other than 1.
 */
 public function registerPrefix($prefix, $className, $filePath = '')
 {
 if (!is_string($prefix) || strlen($prefix) != 1) {
 throw new XML_Query2XML_ConfigException(
 'Prefix name has to be a single character'
 );
 }
 $this->_prefixes[$prefix] = array(
 $filePath,
 $className
 );
 }
 
 /**
 * Unregister a prefix.
 *
 * @param string $prefix The prefix name.
 *
 * @return void
 */
 public function unregisterPrefix($prefix)
 {
 unset($this->_prefixes[$prefix]);
 }
 
 /**
 * Unregister all prefixes.
 *
 * @return void
 */
 public function unregisterAllPrefixes()
 {
 $this->_prefixes = array();
 }
 
 /**
 * Set a global option.
 * Currently the following global options are available:
 *
 * hidden_container_prefix: The prefix to use for container elements that are
 * to be removed before the DOMDocument before it is returned by
 * {@link XML_Query2XML::getXML()}. This has to be a non-empty string.
 * The default value is '__'.
 *
 * @param string $option The name of the option
 * @param mixed $value The option value
 *
 * @return void
 * @throws XML_Query2XML_ConfigException If the configuration option
 * does not exist or if the value is invalid for that option
 */
 public function setGlobalOption($option, $value)
 {
 switch ($option) {
 case 'hidden_container_prefix':
 if (is_string($value) && strlen($value) > 0) {
 // unit test: setGlobalOption/hidden_container_prefix.phpt
 $this->_globalOptions[$option] = $value;
 } else {
 /*
 * unit test: setGlobalOption/
 * configException_hidden_container_prefix_wrongTypeObject.phpt
 * configException_hidden_container_prefix_wrongTypeEmptyStr.phpt
 */
 throw new XML_Query2XML_ConfigException(
 'The value for the hidden_container_prefix option '
 . 'has to be a non-empty string'
 );
 }
 break;

default:
 // unit tests: setGlobalOption/configException_noSuchOption.phpt
 throw new XML_Query2XML_ConfigException(
 'No such global option: ' . $option
 );
 }
 }
 
 /**
 * Returns the current value for a global option.
 * See {@link XML_Query2XML::setGlobalOption()} for a list
 * of available options.
 *
 * @param string $option The name of the option
 *
 * @return mixed The option's value
 * @throws XML_Query2XML_ConfigException If the option does not exist
 */
 public function getGlobalOption($option)
 {
 if (!isset($this->_globalOptions[$option])) {
 // unit test: getGlobalOption/configException_noSuchOption.phpt
 throw new XML_Query2XML_ConfigException(
 'No such global option: ' . $option
 );
 }
 // unit test: getGlobalOption/hidden_container_prefix.phpt
 return $this->_globalOptions[$option];
 }
 
 /**
 * Enable the logging of debug messages.
 * This will include all queries sent to the database.
 * Example:
 * <code>
 * <?php
 * require_once 'Log.php';
 * require_once 'XML/Query2XML.php';
 * $query2xml = XML_Query2XML::factory(MDB2::connect($dsn));
 * $debugLogger = Log::factory('file', 'out.log', 'XML_Query2XML');
 * $query2xml->enableDebugLog($debugLogger);
 * ?>
 * </code>
 * Please see {@link http://pear.php.net/package/Log} for details on PEAR Log.
 *
 * @param mixed $log Most likely an instance of PEAR Log but any object
 * that provides a method named 'log' is accepted.
 *
 * @return void
 */
 public function enableDebugLog($log)
 {
 // unit test: enableDebugLog/enableDebugLog.phpt
 $this->_debugLogger = $log;
 $this->_debug = true;
 }
 
 /**
 * Disable the logging of debug messages
 *
 * @return void
 */
 public function disableDebugLog()
 {
 // unit test: disableDebugLog/disableDebugLog.phpt
 $this->_debug = false;
 }
 
 /**
 * Start profiling.
 *
 * @return void
 */
 public function startProfiling()
 {
 // unit tests: startProfile/startProfile.phpt
 $this->_profiling = true;
 $this->_profile = array(
 'queries' => array(),
 'start' => microtime(1),
 'stop' => 0,
 'duration' => 0,
 'dbStop' => 0,
 'dbDuration' => 0
 );
 }
 
 /**
 * Stop profiling.
 *
 * @return void
 */
 public function stopProfiling()
 {
 // unit test: stopProfile/stopProfile.phpt
 $this->_profiling = false;
 if (isset($this->_profile['start']) && $this->_profile['stop'] == 0) {
 $this->_profile['stop'] = microtime(1);
 $this->_profile['duration'] =
 $this->_profile['stop'] - $this->_profile['start'];
 }
 }
 
 /**
 * Returns all raw profiling data.
 * In 99.9% of all cases you will want to use getProfile().
 *
 * @see getProfile()
 * @return array
 */
 public function getRawProfile()
 {
 // unit test: getRawProfile/getRawProfile.phpt
 $this->stopProfiling();
 return $this->_profile;
 }
 
 /**
 * Returns the profile as a single multi line string.
 *
 * @return string The profiling data.
 */
 public function getProfile()
 {
 // unit test: getProfile/getProfile.phpt
 $this->stopProfiling();
 if (count($this->_profile) === 0) {
 return '';
 }
 $ret = 'COUNT AVG_DURATION DURATION_SUM SQL' . "\n";
 foreach ($this->_profile['queries'] as $sql => $value) {
 $durationSum = 0.0;
 $durationCount = 0;
 $runTimes =& $this->_profile['queries'][$sql]['runTimes'];
 foreach ($runTimes as $runTime) {
 $durationSum += ($runTime['stop'] - $runTime['start']);
 ++$durationCount;
 }
 if ($durationCount == 0) {
 // so that division does not fail
 $durationCount = 1;
 }
 $durationAverage = $durationSum / $durationCount;
 
 $ret .= str_pad($this->_profile['queries'][$sql]['count'], 5)
 . ' '
 . substr($durationAverage, 0, 12). ' '
 . substr($durationSum, 0, 12). ' '
 . $sql . "\n";
 }
 $ret .= "\n";
 $ret .= 'TOTAL_DURATION: ' . $this->_profile['duration'] . "\n";
 $ret .= 'DB_DURATION: ' . $this->_profile['dbDuration'] . "\n";
 return $ret;
 }
 
 /**
 * Calls {@link XML_Query2XML::stopProfiling()} and then clears the profiling
 * data by resetting a private property.
 *
 * @return void
 */
 public function clearProfile()
 {
 // unit test: clearProfile/clearProfile.phpt
 $this->stopProfiling();
 $this->_profile = array();
 }
 
 /**
 * Transforms the data retrieved by a single SQL query into flat XML data.
 *
 * This method will return a new instance of DOMDocument. The column names
 * will be used as element names.
 *
 * Example:
 * <code>
 * <?php
 * require_once 'XML/Query2XML.php';
 * $query2xml = XML_Query2XML::factory(MDB2::connect($dsn));
 * $dom = $query2xml->getFlatXML(
 * 'SELECT * FROM artist',
 * 'music_library',
 * 'artist'
 * );
 * ?>
 * </code>
 *
 * @param string $sql The query string.
 * @param string $rootTagName The name of the root tag; this argument is optional
 * (default: 'root').
 * @param string $rowTagName The name of the tag used for each row; this
 * argument is optional (default: 'row').
 *
 * @return DOMDocument A new instance of DOMDocument.
 * @throws XML_Query2XML_Exception This is the base class for the exception
 * types XML_Query2XML_DBException and
 * XML_Query2XML_XMLException. By catching
 * XML_Query2XML_Exception you can catch all
 * exceptions this method will ever throw.
 * @throws XML_Query2XML_DBException If a database error occurrs.
 * @throws XML_Query2XML_XMLException If an XML error occurrs - most likely
 * $rootTagName or $rowTagName is not a valid
 * element name.
 */
 public function getFlatXML($sql, $rootTagName = 'root', $rowTagName = 'row')
 {
 /*
 * unit tests: getFlatXML/*.phpt
 */
 $dom = self::_createDOMDocument();
 $rootTag = self::_addNewDOMChild($dom, $rootTagName, 'getFlatXML');
 $records = $this->_getAllRecords(array('query' => $sql), 'getFlatXML', $sql);
 foreach ($records as $record) {
 $rowTag = self::_addNewDOMChild($rootTag, $rowTagName, 'getFlatXML');
 foreach ($record as $field => $value) {
 self::_addNewDOMChild(
 $rowTag,
 $field,
 'getFlatXML',
 self::_utf8encode($value)
 );
 }
 }
 return $dom;
 }
 
 /**
 * Transforms your SQL data retrieved by one or more queries into complex and
 * highly configurable XML data.
 *
 * This method will return a new instance of DOMDocument.
 * Please see the {@tutorial XML_Query2XML.pkg tutorial} for details.
 * 
 * @param mixed $sql A string an array or the boolean value false.
 * @param array $options Options for the creation of the XML data stored in an
 * associative, potentially mutli-dimensional array
 * (please see the tutorial).
 *
 * @return DOMDocument The XML data as a new instance of DOMDocument.
 * @throws XML_Query2XML_Exception This is the base class for the exception types
 * XML_Query2XML_DBException, XML_Query2XML_XMLException
 * and XML_Query2XML_ConfigException. By catching
 * XML_Query2XML_Exception you can catch all exceptions
 * this method will ever throw.
 * @throws XML_Query2XML_DBException If a database error occurrs.
 * @throws XML_Query2XML_XMLException If an XML error occurrs - most likely
 * an invalid XML element name.
 * @throws XML_Query2XML_ConfigException If some configuration options passed
 * as second argument are invalid or missing.
 */
 public function getXML($sql, $options)
 {
 /*
 * unit tests: getXML/*.phpt
 */
 
 // the default root tag name is 'root'
 if (isset($options['rootTag'])) {
 $rootTagName = $options['rootTag'];
 } else {
 $rootTagName = 'root';
 }
 
 $dom = self::_createDOMDocument();
 $rootTag = self::_addNewDOMChild($dom, $rootTagName, '[rootTag]');
 
 $options['sql'] = $sql;
 
 if ($options['sql'] === false) {
 $options['sql'] = '';
 }
 $this->_preprocessOptions($options);
 
 /* Used to store the information which element has been created
 * for which ID column value.
 */
 $tree = array();
 
 if ($sql === false) {
 $records = array(array()); // one empty record
 } else {
 $records = $this->_applySqlOptionsToRecord(
 $options,
 $emptyRecord = array()
 );
 }
 
 foreach ($records as $key => $record) {
 $tag = $this->_getNestedXMLRecord($records[$key], $options, $dom, $tree);
 
 /* _getNestedXMLRecord() returns false if an element already existed for
 * the current ID column value.
 */
 if ($tag !== false) {
 $rootTag->appendChild($tag);
 }
 }
 
 $this->_stopDBProfiling();
 
 self::_removeContainers(
 $dom,
 $this->getGlobalOption('hidden_container_prefix')
 );
 return $dom;
 }
 
 /**
 * Perform pre-processing on $options.
 * This is a recursive method; it will call itself for every complex element
 * specification and every complex attribute specification found.
 *
 * @param array &$options An associative array
 * @param string $context Indecates whether an element or an attribute is
 * to be processed.
 *
 * @return void
 * @throws XML_Query2XML_ConfigException If a mandatory option is missing
 * or any option is defined incorrectly.
 */
 private function _preprocessOptions(&$options, $context = 'elements')
 {
 if (!isset($options['--q2x--path'])) {
 // things to do only at the root level
 $options['--q2x--path'] = '';
 
 if (!isset($options['rowTag'])) {
 $options['rowTag'] = 'row';
 }
 
 if (!isset($options['idColumn'])) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_idcolumnOptionMissing.phpt
 */
 throw new XML_Query2XML_ConfigException(
 'The configuration option "idColumn" '
 . 'is missing on the root level.'
 );
 }
 }
 
 foreach (array('encoder', 'mapper') as $option) {
 if (isset($options[$option])) {
 if (
 is_string($options[$option]) &&
 strpos($options[$option], '::') !== false
 ) {
 $options[$option] = explode('::', $options[$option]);
 }
 if (
 $options[$option] !== false
 &&
 !($option == 'encoder' && $options[$option] === null)
 &&
 !($option == 'mapper' && $options[$option] == false)
 &&
 !is_callable($options[$option], false, $callableName)
 ) {
 /*
 * Only check whether $options['encoder'] is callable if it's not
 * set to:
 * - false (don't use an encoder)
 * - null (use self::_utf8encode()).
 *
 * unit test: _preprocessOptions/
 * throwConfigException_encoderNotCallableStaticMethod1.phpt
 * throwConfigException_encoderNotCallableStaticMethod2.phpt
 * throwConfigException_encoderNotCallableNonstaticMethod.phpt
 * throwConfigException_encoderNotCallableFunction.phpt
 *
 *
 * Only check whether $options['mapper'] is callable if
 * - $options['mapper'] != false
 *
 * unit tests: _preprocessOptions/
 * throwConfigException_mapperNotCallableStaticMethod1.phpt
 * throwConfigException_mapperNotCallableStaticMethod2.phpt
 * throwConfigException_mapperNotCallableNonstaticMethod.phpt
 * throwConfigException_mapperNotCallableFunction.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[' . $option . ']: The '
 . 'method/function "' . $callableName . '" is not callable.'
 );
 }
 } else {
 $options[$option] = null;
 }
 }
 
 if ($context == 'elements') {
 foreach (array('elements', 'attributes') as $option) {
 if (isset($options[$option])) {
 if (!is_array($options[$option])) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_attributesOptionWrongType.phpt
 * throwConfigException_elementsOptionWrongType.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[' . $option . ']: '
 . 'array expected, ' . gettype($options[$option])
 . ' given.'
 );
 }
 foreach ($options[$option] as $key => $columnStr) {
 $configPath = $options['--q2x--path'] . '[' . $option
 . '][' . $key . ']';
 if (is_string($columnStr)) {
 $options[$option][$key] =
 $this->_buildCommandChain($columnStr, $configPath);
 if (
 is_numeric($key) &&
 is_object($options[$option][$key])
 ) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_prefix_noArrayKey.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': the element name has to be '
 . 'specified as the array key when prefixes '
 . 'are used within the value specification'
 );
 }
 } elseif (is_array($columnStr)) {
 $options[$option][$key]['--q2x--path'] = $configPath;
 
 // encoder option used by elements as well as attributes
 if (
 !array_key_exists(
 'encoder',
 $options[$option][$key]
 )
 ) {
 $options[$option][$key]['encoder'] =
 $options['encoder'];
 }
 if ($option == 'elements') {
 // these options are only used by elements
 if (
 !isset($options[$option][$key]['rootTag']) ||
 $options[$option][$key]['rootTag'] == ''
 ) {
 /*
 * If rootTag is not set or an empty string:
 * create a hidden root tag
 */
 $options[$option][$key]['rootTag'] = 
 $this->getGlobalOption(
 'hidden_container_prefix'
 ) . $key;
 }
 if (!isset($options[$option][$key]['rowTag'])) {
 $options[$option][$key]['rowTag'] = $key;
 }
 
 foreach (array('mapper', 'idColumn') as $option2) {
 if (
 !array_key_exists(
 $option2,
 $options[$option][$key]
 )
 ) {
 $options[$option][$key][$option2] =
 $options[$option2];
 }
 }
 }
 $this->_preprocessOptions(
 $options[$option][$key],
 $option
 );
 } elseif (self::_isCallback($columnStr)) {
 if (is_numeric($key)) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_callbackInterface_
 * noArrayKey.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': the element name has to be '
 . 'specified as the array key when the value '
 . 'is specified using an instance of '
 . 'XML_Query2XML_Callback.'
 );
 }
 } else {
 /*
 * $columnStr is neither a string, an array or an
 * instance of XML_Query2XML_Callback.
 *
 * unit tests:
 * _getNestedXMLRecord/
 * throwConfigException_attributeSpecWrongType.phpt
 * _preprocessOptions/
 * throwConfigException_callbackInterface_
 * complexAttributeSpec.phpt
 * simpleAttributeSpec.phpt
 * simpleElementSpec.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': array, string or instance of'
 . ' XML_Query2XML_Callback expected, '
 . gettype($columnStr)
 . ' given.'
 );
 }
 }
 }
 } // end of foreach (array('elements', 'attributes'))
 } else {
 // $context == 'attributes'
 if (!isset($options['value'])) {
 /*
 * the option "value" is mandatory
 * unit test: _preprocessOptions/
 * throwConfigException_valueOptionMissing.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[value]: Mandatory option "value" '
 . 'missing from the complex attribute specification.'
 );
 }
 }
 
 $opt = array('value', 'condition', 'dynamicRowTag', 'idColumn');
 foreach ($opt as $option) {
 if (isset($options[$option])) {
 if (is_string($options[$option])) {
 $options[$option] = $this->_buildCommandChain(
 $options[$option],
 $options['--q2x--path'] . '[value]'
 );
 } elseif (
 !self::_isCallback($options[$option]) &&
 !($option == 'idColumn' && $options[$option] === false)
 ) {
 /*
 * unit tests:
 * _preprocessOptions/
 * throwConfigException_callbackInterface_
 * complexElementSpec.phpt
 * condition.phpt
 * idColumn.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[' . $option . ']: string or'
 . ' instance of XML_Query2XML_Callback expected, '
 . gettype($options[$option])
 . ' given.'
 );
 }
 }
 }
 
 if (isset($options['query'])) {
 $options['sql'] = $options['query'];
 }
 if (isset($options['sql'])) {
 
 // we will pre-process $options['sql_options'] first
 if (isset($options['query_options'])) {
 $options['sql_options'] = $options['query_options'];
 }
 if (!isset($options['sql_options'])) {
 $options['sql_options'] = array();
 }
 $sql_options = array(
 'cached', 'single_record', 'merge', 'merge_master', 'merge_selective'
 );
 foreach ($sql_options as $option) {
 if (!isset($options['sql_options'][$option])) {
 $options['sql_options'][$option] = false;
 }
 }
 if (isset($options['sql_options']['uncached'])) {
 $options['sql_options']['cached'] =
 !$options['sql_options']['uncached'];
 }
 
 if ($options['sql_options']['cached']) {
 if (!is_array($options['sql'])) {
 $options['sql'] = array('query' => $options['sql']);
 }
 if (isset($options['sql']['driver'])) {
 $driver = $options['sql']['driver'];
 } else {
 $driver = $this->_driver;
 }
 if (
 !class_exists('XML_Query2XML_Driver_Caching') ||
 !($driver instanceof XML_Query2XML_Driver_Caching)
 ) {
 include_once 'XML/Query2XML/Driver/Caching.php';
 $options['sql']['driver'] = new XML_Query2XML_Driver_Caching(
 $driver
 );
 }
 }
 
 if (
 $options['sql_options']['merge_selective'] !== false &&
 !is_array($options['sql_options']['merge_selective'])
 ) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_mergeselectiveOptionWrongType.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql_options][merge_selective]: '
 . 'array expected, '
 . gettype($options['sql_options']['merge_selective']) . ' given.'
 );
 }
 // end of pre-processing of $options['sql_options']
 
 if (
 is_array($options['sql']) && 
 isset($options['sql']['driver']) &&
 $options['sql']['driver'] instanceof XML_Query2XML_Driver
 ) {
 $query = $options['sql']['driver']->preprocessQuery(
 $options['sql'],
 $options['--q2x--path'] . '[sql]'
 );
 } else {
 $query = $this->_driver->preprocessQuery(
 $options['sql'],
 $options['--q2x--path'] . '[sql]'
 );
 }
 $options['--q2x--query_statement'] = $query;
 if (
 is_array($options['sql']) && 
 isset($options['sql']['driver']) &&
 !($options['sql']['driver'] instanceof XML_Query2XML_Driver)
 ) {
 /*
 * unit test: _preprocessOptions
 * throwConfigException_sqlOptionWrongType.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql][driver]: '
 . 'instance of XML_Query2XML_Driver expected, '
 . gettype($options['sql']['driver']) . ' given.'
 );
 }
 
 if (is_array($options['sql'])) {
 if (isset($options['sql']['data'])) {
 if (is_array($options['sql']['data'])) {
 foreach ($options['sql']['data'] as $key => $data) {
 if (is_string($data)) {
 $options['sql']['data'][$key] =
 $this->_buildCommandChain(
 $options['sql']['data'][$key],
 $options['--q2x--path']
 . '[sql][data][' . $key . ']'
 );
 } elseif (!self::_isCallback($data)) {
 /*
 * unit tests: _preprocessOptions/
 * throwConfigException_callbackInterface_data.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql][data][' . $key
 . ']: string or'
 . ' instance of XML_Query2XML_Callback expected,'
 . ' ' . gettype($options['sql']['data'][$key])
 . ' given.'
 );
 }
 }
 } else {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_dataOptionWrongType.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql][data]: array expected, '
 . gettype($options['sql']['data']) . ' given.'
 );
 }
 }
 }
 } // end of if (isset($options['sql'])
 }
 
 /**
 * Private recursive method that creates the nested XML elements from a record.
 *
 * getXML calls this method for every row in the initial result set.
 * The $tree argument deserves some more explanation. All DOMNodes are stored
 * in $tree the way they appear in the XML document. The same hirachy needs to be
 * built so that we can know if a DOMNode that corresponds to a column ID of 2 is
 * already a child node of a certain XML element. Let's have a look at an example
 * to clarify this:
 * <code>
 * <music_library>
 * <artist>
 * <artistid>1</artistid>
 * <albums>
 * <album>
 * <albumid>1</albumid>
 * </album>
 * <album>
 * <albumid>2</albumid>
 * </album>
 * </albums>
 * </artist>
 * <artist>
 * <artistid>3</artistid>
 * <albums />
 * </artist>
 * </music_library>
 * </code>
 * would be represended in the $tree array as something like this:
 * <code>
 * array (
 * [1] => array (
 * [tag] => DOMElement Object
 * [elements] => array (
 * [albums] => array (
 * [1] => array (
 * [tag] => DOMElement Object
 * )
 * [2] => array (
 * [tag] => DOMElement Object
 * )
 * )
 * )
 * )
 * [2] => array (
 * [tag] => DOMElement Object
 * [elements] => array
 * (
 * [albums] => array ()
 * )
 * )
 * )
 * </code>
 * The numbers in the square brackets are column ID values.
 *
 * @param array $record An associative array representing a record;
 * column names must be used as keys.
 * @param array &$options An array containing the options for this nested 
 * element; this will be a subset of the array
 * originally passed to getXML().
 * @param DOMDocument $dom An instance of DOMDocument.
 * @param array &$tree An associative multi-dimensional array, that is
 * used to store the information which tag has
 * already been created for a certain ID column
 * value. It's format is:
 * Array(
 * "$id1" => Array(
 * 'tag' => DOMElement,
 * 'elements' => Array(
 * "$id2" => Array(
 * 'tag' => DOMElement,
 * 'elements' => Array( ... )
 * ),
 * "$id3" => ...
 * )
 * )
 * )
 *
 * @return mixed The XML element's representation as a new instance of
 * DOMNode or the boolean value false (meaning no
 * new tag was created).
 * @throws XML_Query2XML_DBException Bubbles up through this method if thrown by
 * - _processComplexElementSpecification()
 * @throws XML_Query2XML_XMLException Bubbles up through this method if thrown by
 * - _createDOMElement()
 * - _setDOMAttribute
 * - _appendTextChildNode()
 * - _addNewDOMChild()
 * - _addDOMChildren()
 * - _processComplexElementSpecification()
 * - _expandShortcuts()
 * - _executeEncoder()
 * @throws XML_Query2XML_ConfigException Thrown if
 * - $options['idColumn'] is not set
 * - $options['elements'] is set but not an array
 * - $options['attributes'] is set but not an array
 * Bubbles up through this method if thrown by
 * - _applyColumnStringToRecord()
 * - _processComplexElementSpecification()
 * - _expandShortcuts()
 * @throws XML_Query2XML_Exception Bubbles up through this method if thrown by
 * - _expandShortcuts()
 * - _applyColumnStringToRecord()
 */
 private function _getNestedXMLRecord($record, &$options, $dom, &$tree)
 {
 // the default row tag name is 'row'
 if (isset($options['dynamicRowTag'])) {
 $rowTagName = $this->_applyColumnStringToRecord(
 $options['dynamicRowTag'],
 $record,
 $options['--q2x--path'] . '[dynamicRowTag]'
 );
 } else {
 $rowTagName = $options['rowTag'];
 }
 
 if ($options['idColumn'] === false) {
 static $uniqueIdCounter = 0;
 $id = ++$uniqueIdCounter;
 } else {
 $id = $this->_applyColumnStringToRecord(
 $options['idColumn'],
 $record,
 $options['--q2x--path'] . '[idColumn]'
 );
 
 if ($id === null) {
 // the ID column is NULL
 return false;
 } elseif (is_object($id) || is_array($id)) {
 /*
 * unit test: _getNestedXMLRecord/
 * throwConfigException_idcolumnOptionWrongTypeArray.phpt
 * throwConfigException_idcolumnOptionWrongTypeObject.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[idColumn]: Must evaluate to a '
 . 'value that is not an object or an array.'
 );
 }
 }
 
 /* Is there already an identical tag (identity being determined by the
 * value of the ID-column)?
 */
 if (isset($tree[$id])) {
 if (isset($options['elements'])) {
 foreach ($options['elements'] as $tagName => $column) {
 if (is_array($column)) {
 $this->_processComplexElementSpecification(
 $record,
 $options['elements'][$tagName],
 $tree[$id],
 $tagName
 );
 }
 }
 }
 /*
 * We return false because $tree[$id]['tag'] is already
 * a child of the parent element.
 */
 return false;
 } else {
 $tree[$id] = array();
 
 if (isset($options['value'])) {
 $parsedValue = $this->_applyColumnStringToRecord(
 $options['value'],
 $record,
 $options['--q2x--path'] . '[value]'
 );
 if (!$this->_evaluateCondition($parsedValue, $options['value'])) {
 // this element is to be skipped
 return false;
 }
 }
 if (isset($options['condition'])) {
 $continue = $this->_applyColumnStringToRecord(
 $options['condition'],
 $record,
 $options['--q2x--path'] . '[condition]'
 );
 if (!$continue) {
 // this element is to be skipped
 return false;
 }
 }
 $tree[$id]['tag'] = self::_createDOMElement(
 $dom,
 $rowTagName,
 $options['--q2x--path'] . '[rowTag/dynamicRowTag]'
 );

$tag = $tree[$id]['tag'];
 
 // add attributes
 if (isset($options['attributes'])) {
 if (!isset($options['processed'])) {
 $options['attributes'] = self::_expandShortcuts(
 $options['attributes'],
 $record,
 $options['mapper'],
 $options['--q2x--path'] . '[attributes]'
 );
 }
 foreach ($options['attributes'] as $attributeName => $column) {
 if (is_array($column)) {
 // complex attribute specification
 $this->_processComplexAttributeSpecification(
 $attributeName, $record, $column, $tree[$id]['tag']
 );
 } else {
 // simple attribute specifications
 $attributeValue = $this->_applyColumnStringToRecord(
 $column,
 $record,
 $options['--q2x--path']
 . '[attributes][' . $attributeName . ']'
 );
 if ($this->_evaluateCondition($attributeValue, $column)) {
 self::_setDOMAttribute(
 $tree[$id]['tag'],
 $attributeName,
 self::_executeEncoder(
 $attributeValue,
 $options
 ),
 $options['--q2x--path']
 . '[attributes][' . $attributeName . ']'
 );
 }
 }
 }
 }
 if (isset($options['value'])) {
 if ($parsedValue instanceof DOMNode || is_array($parsedValue)) {
 /*
 * The value returned from _applyColumnStringToRecord() and
 * stored in $parsedValue is an instance of DOMNode or an
 * array of DOMNode instances. _addDOMChildren() will handle
 * both.
 */
 self::_addDOMChildren(
 $tree[$id]['tag'],
 $parsedValue,
 $options['--q2x--path'] . '[value]',
 true
 );
 } else {
 if ($parsedValue !== false && !is_null($parsedValue)) {
 self::_appendTextChildNode(
 $tree[$id]['tag'],
 self::_executeEncoder(
 $parsedValue,
 $options
 ),
 $options['--q2x--path'] . '[value]'
 );
 }
 }
 }
 
 // add child elements
 if (isset($options['elements'])) {
 if (!isset($options['processed'])) {
 $options['elements'] = self::_expandShortcuts(
 $options['elements'],
 $record,
 $options['mapper'],
 $options['--q2x--path'] . '[elements]'
 );
 }
 foreach ($options['elements'] as $tagName => $column) {
 if (is_array($column)) {
 // complex element specification
 $this->_processComplexElementSpecification(
 $record,
 $options['elements'][$tagName],
 $tree[$id],
 $tagName
 );
 } else {
 // simple element specification
 $tagValue = $this->_applyColumnStringToRecord(
 $column,
 $record,
 $options['--q2x--path'] . '[elements][' . $tagName . ']'
 );
 if ($this->_evaluateCondition($tagValue, $column)) {
 if (
 $tagValue instanceof DOMNode ||
 is_array($tagValue)
 ) {
 /*
 * The value returned from
 * _applyColumnStringToRecord() and stored in
 * $tagValue is an instance of DOMNode or an array
 * of DOMNode instances. self::_addDOMChildren()
 * will handle both.
 */
 self::_addDOMChildren(
 self::_addNewDOMChild(
 $tree[$id]['tag'],
 $tagName,
 $options['--q2x--path']
 . '[elements][' . $tagName . ']'
 ),
 $tagValue,
 $options['--q2x--path']
 . '[elements][' . $tagName . ']',
 true
 );
 } else {
 self::_addNewDOMChild(
 $tree[$id]['tag'],
 $tagName,
 $options['--q2x--path']
 . '[elements][' . $tagName . ']',
 self::_executeEncoder(
 $tagValue,
 $options
 )
 );
 }
 }
 }
 }
 }
 
 // some things only need to be done once
 $options['processed'] = true;
 
 /*
 * We return $tree[$id]['tag'] because it needs to be added to it's
 * parent; this is to be handled by the method that called
 * _getNestedXMLRecord().
 */
 return $tree[$id]['tag'];
 }
 }
 
 /**
 * Private method that will expand asterisk characters in an array
 * of simple element specifications.
 *
 * This method gets called to handle arrays specified using the 'elements'
 * or the 'attributes' option. An element specification that contains an
 * asterisk will be duplicated for each column present in $record.
 * Please see the {@tutorial XML_Query2XML.pkg tutorial} for details.
 *
 * @param Array &$elements An array of simple element specifications.
 * @param Array &$record An associative array that represents a single
 * record.
 * @param mixed $mapper A valid argument for call_user_func(), a full method
 * method name (e.g. "MyMapperClass::map") or a value
 * that == false for no special mapping at all.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return Array The extended array.
 * @throws XML_Query2XML_ConfigException If only the column part but not the
 * explicitly defined tagName part contains an asterisk.
 * @throws XML_Query2XML_Exception Will bubble up if it is thrown by
 * _mapSQLIdentifierToXMLName(). This should never
 * happen as _getNestedXMLRecord() already checks if
 * $mapper is callable.
 * @throws XML_Query2XML_XMLException Will bubble up if it is thrown by
 * _mapSQLIdentifierToXMLName() which will happen if the
 * $mapper function called, throws any exception.
 */
 private function _expandShortcuts(&$elements, &$record, $mapper, $configPath)
 {
 $newElements = array();
 foreach ($elements as $tagName => $column) {
 if (is_numeric($tagName)) {
 $tagName = $column;
 }
 if (!is_array($column) && strpos($tagName, '*') !== false) {
 // expand all occurences of '*' to all column names
 foreach ($record as $columnName => $value) {
 $newTagName = str_replace('*', $columnName, $tagName);
 if (is_string($column)) {
 $newColumn = str_replace('*', $columnName, $column);
 } elseif (
 class_exists('XML_Query2XML_Data') &&
 $column instanceof XML_Query2XML_Data
 ) {
 $newColumn = clone $column;
 $callback = $newColumn->getFirstPreProcessor();
 if (
 class_exists('XML_Query2XML_Data_Source') &&
 $callback instanceof XML_Query2XML_Data_Source
 ) {
 $callback->replaceAsterisks($columnName);
 }
 } else {
 $newColumn =& $column;
 }
 // do the mapping
 $newTagName = self::_mapSQLIdentifierToXMLName(
 $newTagName,
 $mapper,
 $configPath . '[' . $tagName . ']'
 );
 if (!isset($newElements[$newTagName])) {
 // only if the tagName hasn't already been used
 $newElements[$newTagName] = $newColumn;
 }
 }
 } else {
 /*
 * Complex element specifications will always be dealt with here.
 * We don't want any mapping or handling of the asterisk shortcut
 * to be done for complex element specifications.
 */
 
 if (!is_array($column)) {
 // do the mapping but not for complex element specifications
 $tagName = self::_mapSQLIdentifierToXMLName(
 $tagName,
 $mapper,
 $configPath . '[' . $tagName . ']'
 );
 }
 
 /*
 * explicit specification without an asterisk;
 * this always overrules an expanded asterisk
 */
 unset($newElements[$tagName]);
 $newElements[$tagName] = $column;
 }
 }
 return $newElements;
 }
 
 /**
 * Maps an SQL identifier to an XML name using the supplied $mapper.
 *
 * @param string $sqlIdentifier The SQL identifier as a string.
 * @param mixed $mapper A valid argument for call_user_func(), a full
 * method method name (e.g. "MyMapperClass::map")
 * or a value that == false for no special mapping
 * at all.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return string The mapped XML name.
 * @throws XML_Query2XML_Exception If $mapper is not callable. This should never
 * happen as _getNestedXMLRecord() already checks
 * if $mapper is callable.
 * @throws XML_Query2XML_XMLException If the $mapper function called, throws any
 * exception.
 */
 private function _mapSQLIdentifierToXMLName($sqlIdentifier, $mapper, $configPath)
 {
 if (!$mapper) {
 // no mapper was defined
 $xmlName = $sqlIdentifier;
 } else {
 if (is_callable($mapper, false, $callableName)) {
 try {
 $xmlName = call_user_func($mapper, $sqlIdentifier);
 } catch (Exception $e) {
 /*
 * This will also catch XML_Query2XML_ISO9075Mapper_Exception
 * if $mapper was "XML_Query2XML_ISO9075Mapper::map".
 * unit test:
 * _mapSQLIdentifierToXMLName/throwXMLException.phpt
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': Could not map "' . $sqlIdentifier
 . '" to an XML name using the mapper '
 . $callableName . ': ' . $e->getMessage()
 );
 }
 } else {
 /*
 * This should never happen as _preprocessOptions() already
 * checks if $mapper is callable. Therefore no unit tests
 * can be provided for this exception.
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': The mapper "' . $callableName
 . '" is not callable.'
 );
 }
 }
 return $xmlName;
 }
 
 /**
 * Private method that processes a complex element specification
 * for {@link XML_Query2XML::_getNestedXMLRecord()}.
 *
 * @param array &$record The current record.
 * @param array &$options The current options.
 * @param array &$tree Associative multi-dimensional array, that is used to
 * store which tags have already been created
 * @param string $tagName The element's name.
 *
 * @return void
 * @throws XML_Query2XML_XMLException This exception will bubble up
 * if it is thrown by _getNestedXMLRecord(),
 * _applySqlOptionsToRecord() or _addDOMChildren().
 * @throws XML_Query2XML_DBException This exception will bubble up
 * if it is thrown by _applySqlOptionsToRecord()
 * or _getNestedXMLRecord().
 * @throws XML_Query2XML_ConfigException This exception will bubble up
 * if it is thrown by _applySqlOptionsToRecord()
 * or _getNestedXMLRecord().
 * @throws XML_Query2XML_Exception This exception will bubble up if it
 * is thrown by _getNestedXMLRecord().
 */
 private function _processComplexElementSpecification(&$record, &$options, &$tree,
 $tagName)
 {
 $tag = $tree['tag'];
 if (!isset($tree['elements'])) {
 $tree['elements'] = array();
 }
 if (!isset($tree['elements'][$tagName])) {
 $tree['elements'][$tagName] = array();
 $tree['elements'][$tagName]['rootTag'] = self::_addNewDOMChild(
 $tag,
 $options['rootTag'],
 $options['--q2x--path'] . '[rootTag]'
 );
 }
 
 $records =& $this->_applySqlOptionsToRecord($options, $record);
 
 for ($i = 0; $i < count($records); $i++) {
 self::_addDOMChildren(
 $tree['elements'][$tagName]['rootTag'],
 $this->_getNestedXMLRecord(
 $records[$i],
 $options,
 $tag->ownerDocument,
 $tree['elements'][$tagName]
 ),
 $options['--q2x--path']
 );
 }
 }
 
 /**
 * Private method that processes a complex attribute specification
 * for {@link XML_Query2XML::_getNestedXMLRecord()}.
 *
 * A complex attribute specification consists of an associative array
 * with the keys 'value' (mandatory), 'condition', 'sql' and 'sql_options'.
 *
 * @param string $attributeName The name of the attribute as it was specified
 * using the array key of the complex attribute
 * specification.
 * @param array &$record The current record.
 * @param array &$options The complex attribute specification itself.
 * @param DOMNode $tag The DOMNode to which the attribute is to be
 * added.
 *
 * @return void
 * @throws XML_Query2XML_XMLException This exception will bubble up
 * if it is thrown by _setDOMAttribute(),
 * _applyColumnStringToRecord(),
 * _applySqlOptionsToRecord() or _executeEncoder().
 * @throws XML_Query2XML_DBException This exception will bubble up
 * if it is thrown by _applySqlOptionsToRecord().
 * @throws XML_Query2XML_ConfigException This exception will bubble up
 * if it is thrown by _applySqlOptionsToRecord() or
 * _applyColumnStringToRecord(). It will also be thrown 
 * by this method if $options['value'] is not set.
 */
 private function _processComplexAttributeSpecification($attributeName, &$record,
 &$options, $tag)
 {
 if (isset($options['condition'])) {
 $continue = $this->_applyColumnStringToRecord(
 $options['condition'],
 $record,
 $options['--q2x--path'] . '[condition]'
 );
 if (!$continue) {
 // this element is to be skipped
 return;
 }
 }
 
 // only fetching a single record makes sense for a single attribute
 $options['sql_options']['single_record'] = true;
 
 $records = $this->_applySqlOptionsToRecord($options, $record);
 if (count($records) == 0) {
 /*
 * $options['sql'] was set but the query did not return any records.
 * Therefore this attribute is to be skipped.
 */
 return;
 }
 $attributeRecord = $records[0];
 
 $attributeValue = $this->_applyColumnStringToRecord(
 $options['value'],
 $attributeRecord,
 $options['--q2x--path'] . '[value]'
 );
 if ($this->_evaluateCondition($attributeValue, $options['value'])) {
 self::_setDOMAttribute(
 $tag,
 $attributeName,
 self::_executeEncoder($attributeValue, $options),
 $options['--q2x--path'] . '[value]'
 );
 }
 }
 
 /**
 * Private method to apply the givenen sql option to a record.
 *
 * This method handles the sql options 'single_record',
 * 'merge', 'merge_master' and 'merge_selective'. Please see the
 * {@tutorial XML_Query2XML.pkg tutorial} for details.
 * 
 * @param array &$options An associative multidimensional array of options.
 * @param array &$record The current record as an associative array.
 *
 * @return array An indexed array of records that are themselves
 * represented as associative arrays.
 * @throws XML_Query2XML_ConfigException This exception is thrown if
 * - a column specified in merge_selective does not exist
 * in the result set
 * - it bubbles up from _applyColumnStringToRecord()
 * @throws XML_Query2XML_DBException This exception will bubble up
 * if it is thrown by _getAllRecords().
 * @throws XML_Query2XML_XMLException It will bubble up if it is thrown
 * by _applyColumnStringToRecord().
 */
 private function _applySqlOptionsToRecord(&$options, &$record)
 {
 if (!isset($options['sql'])) {
 return array($record);
 }
 
 $single_record = $options['sql_options']['single_record'];
 $merge = $options['sql_options']['merge'];
 $merge_master = $options['sql_options']['merge_master'];
 $merge_selective = $options['sql_options']['merge_selective'];

$sql = $options['sql'];
 if (is_array($sql)) {
 if (isset($sql['data'])) {
 foreach ($sql['data'] as $key => $columnStr) {
 $sql['data'][$key] = $this->_applyColumnStringToRecord(
 $columnStr,
 $record,
 $options['--q2x--path'] . '[sql][data][' . $key . ']'
 );
 }
 }
 }
 $sqlConfigPath = $options['--q2x--path'] . '[sql]';
 
 $records =& $this->_getAllRecords(
 $sql,
 $sqlConfigPath,
 $options['--q2x--query_statement']
 );
 if ($single_record && isset($records[0])) {
 $records = array($records[0]);
 }
 
 if (is_array($merge_selective)) {
 // selective merge
 if ($merge_master) {
 // current records are master
 for ($ii = 0; $ii < count($merge_selective); $ii++) {
 for ($i = 0; $i < count($records); $i++) {
 if (!array_key_exists($merge_selective[$ii], $record)) {
 /* Selected field does not exist in the parent record
 * (passed as argumnet $record)
 * unit test: _applySqlOptionsToRecord/
 * throwConfigException_mergeMasterTrue.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql_options]'
 . '[merge_selective]['. $ii . ']: The column "'
 . $merge_selective[$ii] . '" '
 . 'was not found in the result set.'
 );
 }
 if (!array_key_exists($merge_selective[$ii], $records[$i])) {
 // we are the master, so only if it does not yet exist
 $records[$i][$merge_selective[$ii]] =
 $record[$merge_selective[$ii]];
 }
 }
 }
 } else {
 // parent record is master
 for ($ii = 0; $ii < count($merge_selective); $ii++) {
 for ($i = 0; $i < count($records); $i++) {
 if (!array_key_exists($merge_selective[$ii], $record)) {
 /* Selected field does not exist in the parent record
 * (passed as argumnet $record)
 * unit test: _applySqlOptionsToRecord/
 * throwConfigException_mergeMasterFalse.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $options['--q2x--path'] . '[sql_options]'
 . '[merge_selective]['. $ii . ']: The column "'
 . $merge_selective[$ii] . '" '
 . 'was not found in the result set.'
 );
 }
 // parent is master!
 $records[$i][$merge_selective[$ii]] =
 $record[$merge_selective[$ii]];
 }
 }
 }
 } elseif ($merge) {
 // regular merge
 if ($merge_master) {
 for ($i = 0; $i < count($records); $i++) {
 $records[$i] = array_merge($record, $records[$i]);
 } 
 } else {
 for ($i = 0; $i < count($records); $i++) {
 $records[$i] = array_merge($records[$i], $record);
 }
 }
 }
 return $records;
 }
 
 /**
 * Private method to apply a column string to a record.
 * Please see the tutorial for details on the different column strings.
 *
 * @param string $columnStr A valid column name or an instance of a class
 * implementing XML_Query2XML_Callback.
 * @param array &$record The record as an associative array.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return mixed A value that can be cast to a string or an instance of DOMNode.
 * @throws XML_Query2XML_ConfigException Thrown if $columnStr is not
 * a string or an instance of XML_Query2XML_Callback or if
 * $record[$columnStr] does not exist (and $columnStr has
 * no special prefix).
 * @throws XML_Query2XML_XMLException Thrown if the '&' prefix was used
 * but the data was not unserializeable, i.e. not valid XML data.
 */
 private function _applyColumnStringToRecord($columnStr, &$record, $configPath)
 {
 if (self::_isCallback($columnStr)) {
 $value = $columnStr->execute($record);
 } elseif (is_string($columnStr)) {
 if (array_key_exists($columnStr, $record)) {
 $value = $record[$columnStr];
 } else {
 /*
 * unit test:
 * _applyColumnStringToRecord/throwConfigException_element1.phpt
 * _applyColumnStringToRecord/throwConfigException_element2.phpt
 * _applyColumnStringToRecord/throwConfigException_idcolumn.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': The column "' . $columnStr
 . '" was not found in the result set.'
 );
 
 }
 } else {
 // should never be reached
 throw new XML_Query2XML_ConfigException(
 $configPath . ': string or instance of XML_Query2XML_Callback'
 . ' expected, ' . gettype($columnStr) . ' given.'
 );
 }
 return $value;
 }
 
 /**
 * Returns whether $value is to be included in the output.
 * If $spec is a string an is prefixed by a question mark this method will
 * return false if $value is null or is a string with a length of zero. In
 * any other case, this method will return the true.
 *
 * @param string $value The value.
 * @param mixed $spec The value specification. This can be a string
 * or an instance of XML_Query2XML_Callback.
 *
 * @return boolean Whether $value is to be included in the output.
 */
 private function _evaluateCondition($value, $spec)
 {
 return !class_exists('XML_Query2XML_Data_Condition') ||
 !$spec instanceof XML_Query2XML_Data_Condition ||
 $spec->evaluateCondition($value);
 }
 
 /**
 * Private method to fetch all records from a result set.
 *
 * @param mixed $sql The SQL query as a string or an array.
 * @param string $configPath The config path; used for exception messages.
 * @param string $queryStatement The query as a string; it will be used for
 * logging and profiling.
 *
 * @return array An array of records. Each record itself will be an
 * associative array.
 */
 private function &_getAllRecords($sql, $configPath, $queryStatement)
 {
 // $queryStatement will be used for profiling
 if ($this->_profiling || $this->_debug) {
 $loggingQuery = $queryStatement;
 if (is_array($sql) && isset($sql['data']) && is_array($sql['data'])) {
 $loggingQuery .= '; DATA:' . implode(',', $sql['data']);
 }
 $this->_debugStartQuery($loggingQuery, $queryStatement);
 }
 
 if (is_array($sql) && isset($sql['driver'])) {
 $driver = $sql['driver'];
 } else {
 $driver = $this->_driver;
 }
 $records = $driver->getAllRecords($sql, $configPath);
 
 $this->_debugStopQuery($queryStatement);
 return $records;
 }
 
 /**
 * Initializes a query's profile (only used if profiling is turned on).
 *
 * @param mixed &$sql The SQL query as a string or an array.
 *
 * @return void
 * @see startProfiling()
 */
 private function _initQueryProfile(&$sql)
 {
 if (!isset($this->_profile['queries'][$sql])) {
 $this->_profile['queries'][$sql] = array(
 'count' => 0,
 'runTimes' => array()
 );
 }
 }
 
 /**
 * Starts the debugging and profiling of the query passed as argument.
 *
 * @param string $loggingQuery The query statement as it will be logged.
 * @param string $profilingQuery The query statement as it will be used for
 * profiling.
 *
 * @return void
 */
 private function _debugStartQuery($loggingQuery, $profilingQuery)
 {
 $this->_debug('QUERY: ' . $loggingQuery);
 if ($this->_profiling) {
 $this->_initQueryProfile($profilingQuery);
 ++$this->_profile['queries'][$profilingQuery]['count'];
 $this->_profile['queries'][$profilingQuery]['runTimes'][] = array(
 'start' => microtime(true),
 'stop' => 0
 );
 }
 }
 
 /**
 * Ends the debugging and profiling of the query passed as argument.
 *
 * @param string $profilingQuery The query statement as it will be used for
 * profiling.
 *
 * @return void
 */
 private function _debugStopQuery($profilingQuery)
 {
 $this->_debug('DONE');
 if ($this->_profiling) {
 $this->_initQueryProfile($profilingQuery);
 $lastIndex =
 count(
 $this->_profile['queries'][$profilingQuery]['runTimes']
 ) - 1;
 
 $this->_profile['queries'][$profilingQuery]['runTimes'][$lastIndex]['stop'] =
 microtime(true);
 }
 }
 
 /**
 * Stops the DB profiling.
 * This will set $this->_profile['dbDuration'].
 *
 * @return void
 */
 private function _stopDBProfiling()
 {
 if ($this->_profiling && isset($this->_profile['start'])) {
 $this->_profile['dbStop'] = microtime(1);
 $this->_profile['dbDuration'] =
 $this->_profile['dbStop'] - $this->_profile['start'];
 }
 }
 
 /**
 * Private method used to log debug messages.
 * This method will do no logging if $this->_debug is set to false.
 *
 * @param string $msg The message to log.
 *
 * @return void
 * @see _debugLogger
 * @see _debug
 */
 private function _debug($msg)
 {
 if ($this->_debug) {
 $this->_debugLogger->log($msg);
 }
 }
 
 /**
 * Returns whether $object is an instance of XML_Query2XML_Callback.
 *
 * @param mixed $object The variable to check.
 *
 * @return boolean
 */
 private static function _isCallback($object)
 {
 return is_object($object) &&
 interface_exists('XML_Query2XML_Callback') &&
 $object instanceof XML_Query2XML_Callback;
 }
 
 /**
 * Parse specifications that use the prifixes ?, &, =, ^, :, or #.
 *
 * This method will produce a number of chained Data Class objects all of
 * which be an instance of the abstract class XML_Query2XML_Data.
 *
 * @param string $columnStr The original specification.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return mixed An instance of XML_Query2XML_Callback or a column
 * name as a string.
 * @throws XML_Query2XML_ConfigException Bubbles up through this method if
 * thrown by any of the command class
 * constructors.
 */
 private function _buildCommandChain($columnStr, $configPath)
 {
 $prefixList = implode('', array_keys($this->_prefixes));
 if (ltrim($columnStr, $prefixList) == $columnStr) {
 return $columnStr;
 }
 
 $firstCallback = null;
 for ($i = 0; $i < strlen($columnStr); $i++) {
 $prefix = substr($columnStr, $i, 1);
 if (isset($this->_prefixes[$prefix])) {
 $columnSubStr = substr($columnStr, $i + 1);
 $filePath = $this->_prefixes[$prefix][0];
 $className = $this->_prefixes[$prefix][1];
 if ($columnSubStr === false) {
 $columnSubStr = '';
 }
 
 if ($filePath) {
 include_once $filePath;
 }
 
 if (!in_array(
 'XML_Query2XML_Data',
 class_parents($className)
 )
 ) {
 throw new XML_Query2XML_ConfigException(
 $configPath . ': Prefix class ' . $className . ' does ' .
 'not extend XML_Query2XML_Data.'
 );
 }
 
 if (in_array(
 'XML_Query2XML_Data_Source',
 class_parents($className)
 )
 ) {
 // data source prefix
 $callback = call_user_func_array(
 array($className, 'create'),
 array($columnSubStr, $configPath)
 );
 } else {
 // data processing prefix
 $callback = call_user_func_array(
 array($className, 'create'),
 array(null, $configPath)
 );
 
 if (ltrim($columnSubStr, $prefixList) == $columnSubStr) {
 // no more prefixes: ColumnValue is the default data source
 include_once 'XML/Query2XML/Data/Source/ColumnValue.php';
 $callback->setPreProcessor(
 new XML_Query2XML_Data_Source_ColumnValue(
 $columnSubStr,
 $configPath
 )
 );
 }
 }
 
 if (is_null($firstCallback)) {
 $firstCallback = $callback;
 } else {
 if (
 $callback instanceof XML_Query2XML_Data_Condition &&
 !($firstCallback instanceof XML_Query2XML_Data_Condition)
 ) {
 throw new XML_Query2XML_ConfigException(
 $configPath . ': conditional prefixes always have to '
 . 'go first.'
 );
 }
 $firstCallback->getFirstPreProcessor()->setPreProcessor(
 $callback
 );
 }
 if (
 $firstCallback->getFirstPreProcessor()
 instanceof XML_Query2XML_Data_Source
 ) {
 // there can only be one data source
 break;
 }
 } else {
 break;
 }
 }
 if (is_null($firstCallback)) {
 return $columnStr;
 } else {
 return $firstCallback;
 }
 }
 
 /**
 * Creates a new instance of DOMDocument.
 * '1.0' is passed as first argument and 'UTF-8' as second to the
 * DOMDocument constructor.
 *
 * @return DOMDocument The new instance.
 */
 private static function _createDOMDocument()
 {
 return new DOMDocument('1.0', 'UTF-8');
 }
 
 /**
 * Create and then add a new child element.
 *
 * @param DOMNode $element The parent DOMNode the new DOM element should be
 * appended to.
 * @param string $name The tag name of the new element.
 * @param string $configPath The config path; used for exception messages.
 * @param string $value The value of a child text node. This argument is
 * optional. The default is the boolean value false,
 * which means that no child text node will be
 * appended.
 *
 * @return DOMNode The newly created DOMNode instance that was appended
 * to $element.
 * @throws XML_Query2XML_XMLException This exception will bubble up if it is
 * thrown by _createDOMElement().
 */
 private static function _addNewDOMChild(DOMNode $element, $name, $configPath,
 $value = false)
 {
 if ($element instanceof DOMDocument) {
 $dom = $element;
 } else {
 $dom = $element->ownerDocument;
 }
 $child = self::_createDOMElement($dom, $name, $configPath, $value);
 $element->appendChild($child);
 return $child;
 }
 
 /**
 * Helper method to create a new instance of DOMNode
 *
 * @param DOMDocument $dom An instance of DOMDocument. It's
 * createElement() method is used to create the
 * new DOMNode instance.
 * @param string $name The tag name of the new element.
 * @param string $configPath The config path; used for exception messages.
 * @param string $value The value of a child text node. This argument
 * is optional. The default is the boolean value
 * false, which means that no child text node will
 * be appended.
 *
 * @return DOMNode An instance of DOMNode.
 * @throws XML_Query2XML_XMLException If $name is an invalid XML identifier.
 * Also it will bubble up if it is thrown by
 * _appendTextChildNode().
 */
 private static function _createDOMElement(DOMDocument $dom, $name, $configPath,
 $value = false)
 {
 try {
 $element = $dom->createElement($name);
 } catch(DOMException $e) {
 /*
 * unit tests:
 * _createDOMElement/throwXMLException_elementInvalid1.phpt
 * _createDOMElement/throwXMLException_elementInvalid2.phpt
 * _createDOMElement/throwXMLException_roottagOptionInvalid1.phpt
 * _createDOMElement/throwXMLException_roottagOptionInvalid2.phpt
 * _createDOMElement/throwXMLException_rowtagOptionInvalid.phpt
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': "' . $name . '" is an invalid XML element name: '
 . $e->getMessage(),
 $e
 );
 }
 self::_appendTextChildNode($element, $value, $configPath);
 return $element;
 }
 
 /**
 * Append a new child text node to $element.
 * $value must already be UTF8-encoded; this is to be handled
 * by self::_executeEncoder() and $options['encoder'].
 *
 * This method will not create and append a child text node
 * if $value === false || is_null($value).
 *
 * @param DOMNode $element An instance of DOMNode
 * @param string $value The value of the text node.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return void
 * @throws XML_Query2XML_XMLException Any lower-level DOMException will 
 * wrapped and re-thrown as a XML_Query2XML_XMLException. This 
 * will happen if $value cannot be UTF8-encoded for some reason.
 * It will also be thrown if $value is an object or an array
 * (and can therefore not be converted into a string).
 */
 private static function _appendTextChildNode(DOMNode $element,
 $value,
 $configPath)
 {
 if ($value === false || is_null($value)) {
 return;
 } elseif (is_object($value) || is_array($value)) {
 /*
 * Objects and arrays cannot be cast
 * to a string without an error.
 *
 * unit test:
 * _appendTextChildNode/throwXMLException.phpt
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': A value of the type ' . gettype($value)
 . ' cannot be used for a text node.'
 );
 }
 $dom = $element->ownerDocument;
 try {
 $element->appendChild($dom->createTextNode($value));
 } catch(DOMException $e) {
 // this should never happen as $value is UTF-8 encoded
 throw new XML_Query2XML_XMLException(
 $configPath . ': "' . $value . '" is not a vaild text node: '
 . $e->getMessage(),
 $e
 );
 }
 }
 
 /**
 * Set the attribute $name with a value of $value for $element.
 * $value must already be UTF8-encoded; this is to be handled
 * by self::_executeEncoder() and $options['encoder'].
 *
 * @param DOMNode $element An instance of DOMNode
 * @param string $name The name of the attribute to set.
 * @param string $value The value of the attribute to set.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return void
 * @throws XML_Query2XML_XMLException Any lower-level DOMException will be
 * wrapped and re-thrown as a XML_Query2XML_XMLException. This
 * will happen if $name is not a valid attribute name. It will
 * also be thrown if $value is an object or an array (and can
 * therefore not be converted into a string).
 */
 private static function _setDOMAttribute(DOMNode $element,
 $name,
 $value,
 $configPath)
 {
 if (is_object($value) || is_array($value)) {
 /*
 * Objects and arrays cannot be cast
 * to a string without an error.
 *
 * unit test:
 * _setDOMAttribute/throwXMLException.phpt
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': A value of the type ' . gettype($value)
 . ' cannot be used for an attribute value.'
 );
 }
 
 try {
 $element->setAttribute($name, $value);
 } catch(DOMException $e) {
 // no unit test available for this one
 throw new XML_Query2XML_XMLException(
 $configPath . ': "' . $name . '" is an invalid XML attribute name: '
 . $e->getMessage(),
 $e
 );
 }
 }
 
 /**
 * Adds one or more child nodes to an existing DOMNode instance.
 *
 * @param DOMNode $base An instance of DOMNode.
 * @param mixed $children An array of DOMNode instances or
 * just a single DOMNode instance.
 * Boolean values of false are always ignored.
 * @param string $configPath The config path; used for exception messages.
 * @param boolean $import Whether DOMDocument::importNode() should be called
 * for $children. This is necessary if the instance(s)
 * passed as $children was/were created using a
 * different DOMDocument instance. This argument is
 * optional. The default is false.
 *
 * @return void
 * @throws XML_Query2XML_XMLException If one of the specified children
 * is not one of the following: an instance of DOMNode,
 * the boolean value false, or an array containing
 * these two.
 */
 private static function _addDOMChildren(DOMNode $base,
 $children,
 $configPath,
 $import = false)
 {
 if ($children === false) {
 // don't do anything
 return;
 } elseif ($children instanceof DOMNode) {
 // $children is a single complex child
 if ($import) {
 $children = $base->ownerDocument->importNode($children, true);
 }
 $base->appendChild($children);
 } elseif (is_array($children)) {
 for ($i = 0; $i < count($children); $i++) {
 if ($children[$i] === false) {
 // don't do anything
 } elseif ($children[$i] instanceof DOMNode) {
 if ($import) {
 $children[$i] = $base->ownerDocument->importNode(
 $children[$i],
 true
 );
 }
 $base->appendChild($children[$i]);
 } else {
 /*
 * unit tests:
 * _addDOMChildren/throwXMLException_arrayWithObject.phpt
 * _addDOMChildren/throwXMLException_arrayWithString.phpt
 * _addDOMChildren/throwXMLException_arrayWithInt.phpt
 * _addDOMChildren/throwXMLException_arrayWithBool.phpt
 * _addDOMChildren/throwXMLException_arrayWithDouble.phpt
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': DOMNode, false or an array of the two '
 . 'expected, but ' . gettype($children[$i]) . ' given '
 . '(hint: check your callback).'
 );
 }
 }
 } else {
 /*
 * This should never happen because _addDOMChildren() is only called
 * for arrays and instances of DOMNode.
 */
 throw new XML_Query2XML_XMLException(
 $configPath . ': DOMNode, false or an array of the two '
 . 'expected, but ' . gettype($children) . ' given '
 . '(hint: check your callback).'
 );
 }
 }
 
 /**
 * Remove all container elements created by XML_Query2XML to ensure that all
 * elements are correctly ordered.
 *
 * This is a recursive method. This method calls
 * {@link XML_Query2XML::_replaceParentWithChildren()}. For the concept of
 * container elements please see the {@tutorial XML_Query2XML.pkg tutorial}.
 *
 * @param DOMNode $element An instance of DOMNode.
 * @param string $hiddenContainerPrefix The containers that will be removed
 * all start with this string.
 *
 * @return void
 */
 private static function _removeContainers($element, $hiddenContainerPrefix)
 {
 $xpath = new DOMXPath($element);
 $containers = $xpath->query(
 '//*[starts-with(name(),\'' . $hiddenContainerPrefix . '\')]'
 );
 foreach ($containers as $container) {
 if (!is_null($container->parentNode)) {
 self::_replaceParentWithChildren($container);
 }
 }
 }
 
 /**
 * Replace a certain node with its child nodes.
 *
 * @param DOMNode $parent An instance of DOMNode.
 *
 * @return void
 */
 private static function _replaceParentWithChildren(DOMNode $parent)
 {
 
 $child = $parent->firstChild;
 while ($child) {
 $nextChild = $child->nextSibling;
 $parent->removeChild($child);
 $parent->parentNode->insertBefore($child, $parent);
 $child = $nextChild;
 }
 $parent->parentNode->removeChild($parent);
 }
 
 /**
 * Calls an encoder for XML node and attribute values
 * $options['encoder'] can be one of the following:
 * - null: self::_utf8encode() will be used
 * - false: no encoding will be performed
 * - callback: a string or an array as defined by the
 * callback pseudo-type; please see
 * http://www.php.net/manual/en/
 * language.pseudo-types.php#language.types.callback
 *
 * @param string $str The string to encode
 * @param array $options An associative array with $options['encoder'] set.
 *
 * @return void
 * @throws XML_Query2XML_XMLException If the $options['encoder'] is a callback
 * function that threw an exception.
 */
 private static function _executeEncoder($str, $options)
 {
 if (!is_string($str) || $options['encoder'] === false) {
 return $str;
 }
 
 if ($options['encoder'] === null) {
 return self::_utf8encode($str);
 }
 
 try {
 return call_user_func($options['encoder'], $str);
 } catch (Exception $e) {
 /*
 * unit test:
 * _executeEncoder/throwXMLException.phpt
 */
 throw new XML_Query2XML_XMLException(
 $options['--q2x--path'] . '[encoder]: Could not encode '
 . '"' . $str . '": ' . $e->getMessage()
 );
 }
 }
 
 /**
 * UTF-8 encode $str using mb_conver_encoding or if that is not
 * present, utf8_encode.
 *
 * @param string $str The string to encode
 *
 * @return String The UTF-8 encoded version of $str
 */
 private static function _utf8encode($str)
 {
 if (function_exists('mb_convert_encoding')) {
 $str = mb_convert_encoding($str, 'UTF-8');
 } else {
 $str = utf8_encode($str);
 }
 return $str;
 }
}

/**
 * Parent class for ALL exceptions thrown by this package.
 * By catching XML_Query2XML_Exception you will catch all exceptions
 * thrown by XML_Query2XML.
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @link http://pear.php.net/package/XML_Query2XML
 */
class XML_Query2XML_Exception extends PEAR_Exception
{
 
 /**
 * Constructor method
 *
 * @param string $message The error message.
 * @param Exception $exception The Exception that caused this exception 
 * to be thrown. This argument is optional.
 */
 public function __construct($message, $exception = null)
 {
 parent::__construct($message, $exception);
 }
}

/**
 * Exception for driver errors
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @link http://pear.php.net/package/XML_Query2XML
 * @since Release 1.6.0RC1
 */
class XML_Query2XML_DriverException extends XML_Query2XML_Exception
{
 /**
 * Constructor
 *
 * @param string $message The error message.
 */
 public function __construct($message)
 {
 parent::__construct($message);
 }
}

/**
 * Exception for database errors
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @link http://pear.php.net/package/XML_Query2XML
 */
class XML_Query2XML_DBException extends XML_Query2XML_DriverException
{
 /**
 * Constructor
 *
 * @param string $message The error message.
 */
 public function __construct($message)
 {
 parent::__construct($message);
 }
}

/**
 * Exception for XML errors
 * In most cases this exception will be thrown if a DOMException occurs.
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @link http://pear.php.net/package/XML_Query2XML
 */
class XML_Query2XML_XMLException extends XML_Query2XML_Exception
{
 /**
 * Constructor
 *
 * @param string $message The error message.
 * @param DOMException $exception The DOMException that caused this exception 
 * to be thrown. This argument is optional.
 */
 public function __construct($message, DOMException $exception = null)
 {
 parent::__construct($message, $exception);
 }
}

/**
 * Exception that handles configuration errors.
 *
 * This exception handels errors in the $options array passed to
 * XML_Query2XML::getXML() and wrong arguments passed to the constructor via
 * XML_Query2XML::factory().
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @link http://pear.php.net/package/XML_Query2XML
 * @see XML_Query2XML::getXML()
 */
class XML_Query2XML_ConfigException extends XML_Query2XML_Exception
{
 /**
 * Constructor method
 *
 * @param string $message A detailed error message.
 */
 public function __construct($message)
 {
 parent::__construct($message);
 }
}

/**
 * Abstract driver class.
 *
 * usage:
 * <code>
 * $driver = XML_Query2XML_Driver::factory($backend);
 * </code>
 *
 * @category XML
 * @package XML_Query2XML
 * @author Lukas Feiler <lukas.feiler@lukasfeiler.com>
 * @license http://www.gnu.org/copyleft/lesser.html LGPL Version 2.1
 * @version Release: 1.7.2
 * @link http://pear.php.net/package/XML_Query2XML
 * @since Release 1.5.0RC1
 */
abstract class XML_Query2XML_Driver
{
 /**
 * This method, when implemented executes the query passed as the
 * first argument and returns all records from the result set.
 *
 * The format of the first argument depends on the driver being used.
 *
 * @param mixed $sql The SQL query as a string or an array.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return array An array of records. Each record itself will be an
 * associative array.
 * @throws XML_Query2XML_DriverException If some driver related error occures.
 */
 abstract public function getAllRecords($sql, $configPath);
 
 /**
 * Pre-processes a query specification and returns a string representation
 * of the query.
 *
 * The returned string will be used for logging purposes. It
 * does not need to be valid SQL.
 *
 * If $query is a string, it will be changed to array('query' => $query).
 *
 * @param mixed &$query A string or an array containing the element 'query'.
 * @param string $configPath The config path; used for exception messages.
 *
 * @return string The query statement as a string.
 * @throws XML_Query2XML_ConfigException If $query is an array but does not
 * contain the element 'query'.
 */
 public function preprocessQuery(&$query, $configPath)
 {
 if (is_string($query)) {
 $query = array('query' => $query);
 } elseif (is_array($query)) {
 if (!isset($query['query'])) {
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_queryOptionMissing.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': The configuration option'
 . ' "query" is missing.'
 );
 }
 } else { //neither a string nor an array
 /*
 * unit test: _preprocessOptions/
 * throwConfigException_sqlOptionWrongType.phpt
 */
 throw new XML_Query2XML_ConfigException(
 $configPath . ': array or string expected, '
 . gettype($query) . ' given.'
 );
 }
 return $query['query'];
 }
 
 /**
 * Factory method.
 *
 * @param mixed $backend An instance of MDB2_Driver_Common, PDO, DB_common,
 * ADOConnection, Net_LDAP2 or Net_LDAP.
 *
 * @return XML_Query2XML_Driver An instance of a driver class that
 * extends XML_Query2XML_Driver.
 * @throws XML_Query2XML_DriverException If $backend already is a PEAR_Error.
 * @throws XML_Query2XML_ConfigException If $backend is not an instance of a
 * child class of MDB2_Driver_Common, PDO, DB_common,
 * ADOConnection, Net_LDAP2 or Net_LDAP.
 */
 public static function factory($backend)
 {
 if (
 class_exists('MDB2_Driver_Common') &&
 $backend instanceof MDB2_Driver_Common
 ) {
 include_once 'XML/Query2XML/Driver/MDB2.php';
 return new XML_Query2XML_Driver_MDB2($backend);
 } elseif (class_exists('PDO') && $backend instanceof PDO) {
 include_once 'XML/Query2XML/Driver/PDO.php';
 return new XML_Query2XML_Driver_PDO($backend);
 } elseif (class_exists('DB_common') && $backend instanceof DB_common) {
 include_once 'XML/Query2XML/Driver/DB.php';
 return new XML_Query2XML_Driver_DB($backend);
 } elseif (
 class_exists('ADOConnection') &&
 $backend instanceof ADOConnection
 ) {
 include_once 'XML/Query2XML/Driver/ADOdb.php';
 return new XML_Query2XML_Driver_ADOdb($backend);
 } elseif (class_exists('Net_LDAP') && $backend instanceof Net_LDAP) {
 include_once 'XML/Query2XML/Driver/LDAP.php';
 return new XML_Query2XML_Driver_LDAP($backend);
 } elseif (class_exists('Net_LDAP2') && $backend instanceof Net_LDAP2) {
 include_once 'XML/Query2XML/Driver/LDAP2.php';
 return new XML_Query2XML_Driver_LDAP2($backend);
 } elseif (class_exists('PEAR_Error') && $backend instanceof PEAR_Error) {
 //unit tests: NoDBLayer/factory/throwDBException.phpt
 throw new XML_Query2XML_DriverException(
 'Driver error: ' . $backend->toString()
 );
 } else {
 //unit test: NoDBLayer/factory/throwConfigException.phpt
 throw new XML_Query2XML_ConfigException(
 'Argument passed to the XML_Query2XML constructor is not an '
 . 'instance of DB_common, MDB2_Driver_Common, ADOConnection'
 . ', PDO, Net_LDAP or Net_LDAP2.'
 );
 }
 }
}
?>