class.ilAssOrderingElementList.php

Go to the documentation of this file.

<?php
/* Copyright (c) 1998-2013 ILIAS open source, Extended GPL, see docs/LICENSE */
 
require_once 'Modules/TestQuestionPool/classes/questions/class.ilAssOrderingElement.php';
 
class ilAssOrderingElementList implements Iterator
{
        static $objectInstanceCounter = 0;
        public $objectInstanceId;
 
        const SOLUTION_IDENTIFIER_BUILD_MAX_TRIES = 1000;
        const SOLUTION_IDENTIFIER_VALUE_INTERVAL = 1;
        const SOLUTION_IDENTIFIER_START_VALUE = 0;
        
        const RANDOM_IDENTIFIER_BUILD_MAX_TRIES = 1000;
        const RANDOM_IDENTIFIER_RANGE_LOWER_BOUND = 1;
        const RANDOM_IDENTIFIER_RANGE_UPPER_BOUND = 100000;
        
        const FALLBACK_DEFAULT_ELEMENT_RANDOM_IDENTIFIER = 0;
        const JS_ADDED_ELEMENTS_RANDOM_IDENTIFIER_START_VALUE = -1;
        const JS_ADDED_ELEMENTS_RANDOM_IDENTIFIER_VALUE_INTERVAL = -1;
        
        const IDENTIFIER_TYPE_SOLUTION = 'SolutionIds';
        const IDENTIFIER_TYPE_RANDOM = 'RandomIds';
        
        protected static $identifierRegistry = array(
                self::IDENTIFIER_TYPE_SOLUTION => array(),
                self::IDENTIFIER_TYPE_RANDOM => array()
        );
        
        protected $questionId;
        
        protected $elements;
        
        public function __construct()
        {
                $this->objectInstanceId = ++self::$objectInstanceCounter;
                
                $this->questionId = null;
                $this->resetElements();
        }
 
        public function __clone()
        {
                $this->objectInstanceId = ++self::$objectInstanceCounter;
 
                $elements = array();
                
                foreach($this as $key => $element)
                {
                        $elements[$key] = clone $element;
                }
                
                $this->elements = $elements;
        }
        
        public function getClone()
        {
                $that = clone $this;
                return $that;
        }
        
        public function getQuestionId()
        {
                return $this->questionId;
        }
        
        public function setQuestionId($questionId)
        {
                $this->questionId = $questionId;
        }
        
        public function loadFromDb()
        {
                $ilDB = isset($GLOBALS['DIC']) ? $GLOBALS['DIC']['ilDB'] : $GLOBALS['ilDB'];
                
                $result = $ilDB->queryF(
                        "SELECT * FROM qpl_a_ordering WHERE question_fi = %s ORDER BY position ASC",
                        array('integer'), array($this->getQuestionId())
                );
                
                while( $row = $ilDB->fetchAssoc($result) )
                {
                        $element = new ilAssOrderingElement();
                        
                        $element->setRandomIdentifier($row['random_id']);
                        $element->setSolutionIdentifier($row['solution_key']);
                        
                        $element->setPosition($row['position']);
                        $element->setIndentation($row["depth"]);
                        
                        $element->setContent($row['answertext']);
                        
                        $this->addElement($element);
                        $this->registerIdentifiers($element);
                }
        }
        
        public function saveToDb()
        {
                $ilDB = isset($GLOBALS['DIC']) ? $GLOBALS['DIC']['ilDB'] : $GLOBALS['DIC']['ilDB'];  
                
                $ilDB->manipulateF(
                        "DELETE FROM qpl_a_ordering WHERE question_fi = %s",
                        array( 'integer' ), array( $this->getQuestionId() )
                );
                
                foreach($this as $orderElement)
                {
                        $this->ensureValidIdentifiers($orderElement);
                        
                        $ilDB->insert('qpl_a_ordering', array(
                                'answer_id' => array( 'integer', $ilDB->nextId('qpl_a_ordering') ),
                                'question_fi' => array( 'integer', $this->getQuestionId() ),
                                'answertext' => array( 'text', $orderElement->getContent()),
                                'solution_key' => array( 'integer', $orderElement->getSolutionIdentifier() ),
                                'random_id' => array( 'integer', $orderElement->getRandomIdentifier() ),
                                'position' => array( 'integer', $orderElement->getPosition() ),
                                'depth' => array( 'integer', $orderElement->getIndentation() ),
                                'tstamp' => array( 'integer', time() )
                        ));
                }
        }
        
        public function clearElementContents()
        {
                foreach($this as $orderingElement)
                {
                        $orderingElement->setContent('');
                }
        }
        
        public function countElements()
        {
                return count($this->elements);
        }
        
        public function isFirstElementPosition($position)
        {
                return $position == 0;
        }
        
        public function isLastElementPosition($position)
        {
                return $position == ($this->countElements() - 1);
        }
        
        public function moveElementByPositions($currentPosition, $targetPosition)
        {
                $movingElement = $this->getElementByPosition($currentPosition);
                $dodgingElement = $this->getElementByPosition($targetPosition);
                
                $elementList = new self();
                $elementList->setQuestionId($this->getQuestionId());
                
                foreach($this as $element)
                {
                        if( $element->getPosition() == $currentPosition )
                        {
                                $elementList->addElement($dodgingElement);
                                continue;
                        }
                        
                        if( $element->getPosition() == $targetPosition )
                        {
                                $elementList->addElement($movingElement);
                                continue;
                        }
                        
                        $elementList->addElement($element);
                }
                
                $dodgingElement->setPosition($currentPosition);
                $movingElement->setPosition($targetPosition);
                
                $this->setElements( $elementList->getElements() );
        }
        
        public function removeElement(ilAssOrderingElement $removeElement)
        {
                $elementList = new self();
                $elementList->setQuestionId($this->getQuestionId());
                
                $positionCounter = 0;
                
                foreach($this as $element)
                {
                        if( $element->isSameElement($removeElement) )
                        {
                                continue;
                        }
                        
                        $element->setPosition($positionCounter++);
                        $elementList->addElement($element);
                }
        }
        
        public function resetElements()
        {
                $this->elements = array();
        }
        
        public function setElements($elements)
        {
                $this->resetElements();
                
                foreach($elements as $element)
                {
                        $this->addElement($element);
                }
        }
        
        public function getElements()
        {
                return $this->elements;
        }
        
        public function getRandomIdentifierIndexedElements()
        {
                return $this->getIndexedElements(self::IDENTIFIER_TYPE_RANDOM);
        }
        
        public function getRandomIdentifierIndex()
        {
                return array_keys($this->getRandomIdentifierIndexedElements());
        }
        
        public function getSolutionIdentifierIndexedElements()
        {
                return $this->getIndexedElements(self::IDENTIFIER_TYPE_SOLUTION);
        }
        
        public function getSolutionIdentifierIndex()
        {
                return array_keys($this->getSolutionIdentifierIndexedElements());
        }
        
        protected function getIndexedElements($identifierType)
        {
                $elements = array();
                
                foreach($this as $element)
                {
                        $elements[$this->fetchIdentifier($element, $identifierType)] = $element;
                }
                
                return $elements;
        }
        
        public function addElement(ilAssOrderingElement $element)
        {
                if( $this->hasValidIdentifiers($element) )
                {
                        $this->registerIdentifiers($element);
                }
                
                $this->elements[] = $element;
        }
        
        public function getElementByPosition($position)
        {
                if( isset($this->elements[$position]) )
                {
                        return $this->elements[$position];
                }
                
                return null;
        }
        
        public function elementExistByPosition($position)
        {
                return ( $this->getElementByPosition($position) !== null );
        }
        
        public function getElementByRandomIdentifier($randomIdentifier)
        {
                foreach($this as $element)
                {
                        if( $element->getRandomIdentifier() != $randomIdentifier )
                        {
                                continue;
                        }
                        
                        return $element;
                }
                
                return null;
        }
        
        public function elementExistByRandomIdentifier($randomIdentifier)
        {
                return ( $this->getElementByRandomIdentifier($randomIdentifier) !== null );
        }
        
        public function getElementBySolutionIdentifier($solutionIdentifier)
        {
                foreach($this as $element)
                {
                        if( $element->getSolutionIdentifier() != $solutionIdentifier )
                        {
                                continue;
                        }
                        
                        return $element;
                }
                return null;
        }
        
        public function elementExistBySolutionIdentifier($solutionIdentifier)
        {
                return ( $this->getElementBySolutionIdentifier($solutionIdentifier) !== null );
        }
        
        protected function getRegisteredSolutionIdentifiers()
        {
                return $this->getRegisteredIdentifiers(self::IDENTIFIER_TYPE_SOLUTION);
        }
        
        protected function getRegisteredRandomIdentifiers()
        {
                return $this->getRegisteredIdentifiers(self::IDENTIFIER_TYPE_RANDOM);
        }
        
        protected function getRegisteredIdentifiers($identifierType)
        {
                if( !isset(self::$identifierRegistry[$identifierType][$this->getQuestionId()]) )
                {
                        return array();
                }
                
                return self::$identifierRegistry[$identifierType][$this->getQuestionId()];
        }
        
        protected function hasValidIdentifiers(ilAssOrderingElement $element)
        {
                $identifier = $this->fetchIdentifier($element, self::IDENTIFIER_TYPE_SOLUTION);
 
                if( !$this->isValidIdentifier(self::IDENTIFIER_TYPE_SOLUTION, $identifier) )
                {
                        return false;
                }
                
                $identifier = $this->fetchIdentifier($element, self::IDENTIFIER_TYPE_RANDOM);
 
                if( !$this->isValidIdentifier(self::IDENTIFIER_TYPE_RANDOM, $identifier) )
                {
                        return false;
                }
                
                return true;
        }
        
        protected function ensureValidIdentifiers(ilAssOrderingElement $element)
        {
                $this->ensureValidIdentifier($element, self::IDENTIFIER_TYPE_SOLUTION);
                $this->ensureValidIdentifier($element, self::IDENTIFIER_TYPE_RANDOM);
        }
        
        protected function ensureValidIdentifier(ilAssOrderingElement $element, $identifierType)
        {
                $identifier = $this->fetchIdentifier($element, $identifierType);
                
                if( !$this->isValidIdentifier($identifierType, $identifier) )
                {
                        $identifier = $this->buildIdentifier($identifierType);
                        $this->populateIdentifier($element, $identifierType, $identifier);
                        $this->registerIdentifier($element, $identifierType);
                }
        }
        
        protected function registerIdentifiers(ilAssOrderingElement $element)
        {
                $this->registerIdentifier($element, self::IDENTIFIER_TYPE_SOLUTION);
                $this->registerIdentifier($element, self::IDENTIFIER_TYPE_RANDOM);
        }
        
        protected function registerIdentifier(ilAssOrderingElement $element, $identifierType)
        {
                if( !isset(self::$identifierRegistry[$identifierType][$this->getQuestionId()]) )
                {
                        self::$identifierRegistry[$identifierType][$this->getQuestionId()] = array();
                }
                
                $identifier = $this->fetchIdentifier($element, $identifierType);
                
                if( !in_array($identifier, self::$identifierRegistry[$identifierType][$this->getQuestionId()]) )
                {
                        self::$identifierRegistry[$identifierType][$this->getQuestionId()][] = $identifier;
                }
        }
        
        protected function isIdentifierRegistered(ilAssOrderingElement $element, $identifierType)
        {
                if( !isset(self::$identifierRegistry[$identifierType][$this->getQuestionId()]) )
                {
                        return false;
                }
                
                $identifier = $this->fetchIdentifier($element, $identifierType);
                
                if( !in_array($identifier, self::$identifierRegistry[$identifierType][$this->getQuestionId()]) )
                {
                        return false;
                }
                
                return true;
        }
        
        protected function fetchIdentifier(ilAssOrderingElement $element, $identifierType)
        {
                switch($identifierType)
                {
                        case self::IDENTIFIER_TYPE_SOLUTION: return $element->getSolutionIdentifier();
                        case self::IDENTIFIER_TYPE_RANDOM: return $element->getRandomIdentifier();
                }
                
                $this->throwUnknownIdentifierTypeException($identifierType);
        }
        
        protected function populateIdentifier(ilAssOrderingElement $element, $identifierType, $identifier)
        {
                switch($identifierType)
                {
                        case self::IDENTIFIER_TYPE_SOLUTION: $element->setSolutionIdentifier($identifier); break;
                        case self::IDENTIFIER_TYPE_RANDOM: $element->setRandomIdentifier($identifier); break;
                        default: $this->throwUnknownIdentifierTypeException($identifierType);
                }
        }
        
        protected function isValidIdentifier($identifierType, $identifier)
        {
                switch($identifierType)
                {
                        case self::IDENTIFIER_TYPE_SOLUTION:
                                return self::isValidSolutionIdentifier($identifier);
                        
                        case self::IDENTIFIER_TYPE_RANDOM:
                                return self::isValidRandomIdentifier($identifier);
                }
                
                $this->throwUnknownIdentifierTypeException($identifierType);
        }
        
        protected function buildIdentifier($identifierType)
        {
                switch($identifierType)
                {
                        case self::IDENTIFIER_TYPE_SOLUTION: return $this->buildSolutionIdentifier();
                        case self::IDENTIFIER_TYPE_RANDOM: return $this->buildRandomIdentifier();
                }
                
                $this->throwUnknownIdentifierTypeException($identifierType);
        }
        
        protected function throwUnknownIdentifierTypeException($identifierType)
        {
                throw new ilTestQuestionPoolException(
                        "unknown identifier type given (type: $identifierType)"
                );
        }
        
        protected function throwCouldNotBuildRandomIdentifierException($maxTries)
        {
                throw new ilTestQuestionPoolException(
                        "could not build random identifier (max tries: $maxTries)"
                );
        }
        
        protected function throwMissingReorderPositionException($randomIdentifier)
        {
                throw new ilTestQuestionPoolException(
                        "cannot reorder element due to missing position (random identifier: $randomIdentifier)"
                );
        }
        
        protected function throwUnknownRandomIdentifiersException($randomIdentifiers)
        {
                throw new ilTestQuestionPoolException(
                        'cannot reorder element due to one or more unknown random identifiers '.
                        '(' . implode(', ', $randomIdentifiers) . ')'
                );
        }
        
        protected function getLastSolutionIdentifier()
        {
                $lastSolutionIdentifier = null;
                
                foreach( $this->getRegisteredSolutionIdentifiers() as $registeredIdentifier)
                {
                        if( $lastSolutionIdentifier > $registeredIdentifier )
                        {
                                continue;
                        }
                        
                        $lastSolutionIdentifier = $registeredIdentifier;
                }
                
                return $lastSolutionIdentifier;
        }
        
        protected function buildSolutionIdentifier()
        {
                $lastSolutionIdentifier = $this->getLastSolutionIdentifier();
                
                if( $lastSolutionIdentifier === null )
                {
                        return 0;
                }
                
                $nextSolutionIdentifier = $lastSolutionIdentifier + self::SOLUTION_IDENTIFIER_VALUE_INTERVAL;
                
                return $nextSolutionIdentifier;
        }
        
        protected function buildRandomIdentifier()
        {
                $usedTriesCounter = 0;
                
                do
                {
                        if( $usedTriesCounter >= self::RANDOM_IDENTIFIER_BUILD_MAX_TRIES )
                        {
                                $this->throwCouldNotBuildRandomIdentifierException(self::RANDOM_IDENTIFIER_BUILD_MAX_TRIES);
                        }
                        
                        $usedTriesCounter++;
                        
                        $lowerBound = self::RANDOM_IDENTIFIER_RANGE_LOWER_BOUND;
                        $upperBound = self::RANDOM_IDENTIFIER_RANGE_UPPER_BOUND;
                        $randomIdentifier = mt_rand($lowerBound, $upperBound);
                        
                        $testElement = new ilAssOrderingElement();
                        $testElement->setRandomIdentifier($randomIdentifier);
                }
                while( $this->isIdentifierRegistered($testElement, self::IDENTIFIER_TYPE_RANDOM)  );
                
                return $randomIdentifier;
        }
        
        public static function isValidSolutionIdentifier($identifier)
        {
                if( !is_numeric($identifier) )
                {
                        return false;
                }
                
                if( $identifier != (int)$identifier )
                {
                        return false;
                }
                
                if( $identifier < 0 )
                {
                        return false;
                }
                
                return true;
        }
        
        public static function isValidRandomIdentifier($identifier)
        {
                if( !is_numeric($identifier) )
                {
                        return false;
                }
                
                if( $identifier != (int)$identifier )
                {
                        return false;
                }
                
                if( $identifier < self::RANDOM_IDENTIFIER_RANGE_LOWER_BOUND )
                {
                        return false;
                }
                
                if( $identifier > self::RANDOM_IDENTIFIER_RANGE_UPPER_BOUND )
                {
                        return false;
                }
                
                return true;
        }
        
        public static function isValidPosition($position)
        {
                return self::isValidSolutionIdentifier($position); // this was the position earlier
        }
        
        public static function isValidIndentation($indentation)
        {
                return self::isValidPosition($indentation); // horizontal position ^^
        }
        
        public function distributeNewRandomIdentifiers()
        {
                foreach($this as $element)
                {
                        $element->setRandomIdentifier( $this->buildRandomIdentifier() );
                }
        }
        
        public function hasSameElementSetByRandomIdentifiers(self $otherList)
        {
                $numIntersectingElements = count(array_intersect(
                        $otherList->getRandomIdentifierIndex(), $this->getRandomIdentifierIndex()
                ));
                
                if( $numIntersectingElements != $this->countElements() )
                {
                        return false;
                }
                
                if( $numIntersectingElements != $otherList->countElements() )
                {
                        return false;
                }
                
                return true; // faster ;-)
                
                $otherListRandomIdentifierIndex = $otherList->getRandomIdentifierIndex();
                
                foreach($this as $orderingElement)
                {
                        if( !in_array($orderingElement->getRandomIdentifier(), $otherListRandomIdentifierIndex) )
                        {
                                return false;
                        }
                        
                        $randomIdentifierIndexMatchingsCount = count( array_keys(
                                $otherListRandomIdentifierIndex, $orderingElement->getRandomIdentifier(), false
                        ));
                        
                        if( $randomIdentifierIndexMatchingsCount != 1 )
                        {
                                return false;
                        }
                }
                
                return $this->countElements() == $otherList->countElements();
        }
        
        public function getParityTrueElementList(self $otherList)
        {
                if( !$this->hasSameElementSetByRandomIdentifiers($otherList) )
                {
                        throw new ilTestQuestionPoolException('cannot compare lists having different element sets');
                }
                
                $parityTrueElementList = new self();
                $parityTrueElementList->setQuestionId($this->getQuestionId());
                
                foreach($this as $thisElement)
                {
                        $otherElement = $otherList->getElementByRandomIdentifier(
                                $thisElement->getRandomIdentifier()
                        );
                        
                        if( $otherElement->getPosition() != $thisElement->getPosition() )
                        {
                                continue;
                        }
                        
                        if( $otherElement->getIndentation() != $thisElement->getIndentation() )
                        {
                                continue;
                        }
                        
                        $parityTrueElementList->addElement($thisElement);
                }
                
                return $parityTrueElementList;
        }
        
        public function reorderByRandomIdentifiers($randomIdentifiers)
        {
                $positionsMap = array_flip( array_values($randomIdentifiers) );
                
                $orderedElements = array();
                
                foreach($this as $element)
                {
                        if( !isset($positionsMap[$element->getRandomIdentifier()]) )
                        {
                                $this->throwMissingReorderPositionException($element->getRandomIdentifier());
                        }
                        
                        $position = $positionsMap[$element->getRandomIdentifier()];
                        unset($positionsMap[$element->getRandomIdentifier()]);
                        
                        $element->setPosition($position);
                        $orderedElements[$position] = $element;
                }
                
                if( count($positionsMap) )
                {
                        $this->throwUnknownRandomIdentifiersException( array_keys($positionsMap) );
                }
                
                ksort($orderedElements);
                
                $this->setElements( array_values($orderedElements) );
        }
        
        public function resetElementsIndentations()
        {
                foreach($this as $element)
                {
                        $element->setIndentation(0);
                }
        }
        
        public function getDifferenceElementList(self $otherElementList)
        {
                $differenceRandomIdentifierIndex = $this->getDifferenceRandomIdentifierIndex($otherElementList);
                
                $differenceElementList = new self();
                $differenceElementList->setQuestionId($this->getQuestionId());
                
                foreach($differenceRandomIdentifierIndex as $randomIdentifier)
                {
                        $element = $this->getElementByRandomIdentifier($randomIdentifier);
                        $differenceElementList->addElement($element);
                }
                
                return $differenceElementList;
        }
        
        protected function getDifferenceRandomIdentifierIndex(self $otherElementList)
        {
                $differenceRandomIdentifierIndex = array_diff(
                        $this->getRandomIdentifierIndex(), $otherElementList->getRandomIdentifierIndex()
                );
                
                return $differenceRandomIdentifierIndex;
        }
        
        public function completeContentsFromElementList(self $otherList)
        {
                foreach($this as $thisElement)
                {
                        if( !$otherList->elementExistByRandomIdentifier($thisElement->getRandomIdentifier()) )
                        {
                                continue;
                        }
                        
                        $otherElement = $otherList->getElementByRandomIdentifier(
                                $thisElement->getRandomIdentifier()
                        );
                        
                        $thisElement->setContent( $otherElement->getContent() );
                }
        }
        
        public function current() { return current($this->elements); }
        
        public function next() { return next($this->elements); }
        
        public function key() { return key($this->elements); }
        
        public function valid() { return ($this->key() !== null); }
        
        public function rewind() { return reset($this->elements); }
        
        public static function getFallbackDefaultElement()
        {
                $element = new ilAssOrderingElement();
                $element->setRandomIdentifier(self::FALLBACK_DEFAULT_ELEMENT_RANDOM_IDENTIFIER);
 
                return $element;
        }
        
        public static function buildInstance($questionId, $orderingElements = array())
        {
                $elementList = new self();
                
                $elementList->setQuestionId($questionId);
                $elementList->setElements($orderingElements);
                
                return $elementList;
        }
}