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
{
    public 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;
    }
}