MDL-37893 Always notify pending starts before dispatching chunk
[moodle.git] / backup / util / xml / parser / processors / grouped_parser_processor.class.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * @package moodlecore
20  * @subpackage xml
21  * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 require_once($CFG->dirroot.'/backup/util/xml/parser/processors/simplified_parser_processor.class.php');
27 /**
28  * Abstract xml parser processor able to group chunks as configured
29  * and dispatch them to other arbitrary methods
30  *
31  * This @progressive_parser_processor handles the requested paths,
32  * allowing to group information under any of them, dispatching them
33  * to the methods specified
34  *
35  * Note memory increases as you group more and more paths, so use it for
36  * well-known structures being smaller enough (never to group MBs into one
37  * in-memory structure)
38  *
39  * TODO: Complete phpdocs
40  */
41 abstract class grouped_parser_processor extends simplified_parser_processor {
43     protected $groupedpaths; // Paths we are requesting grouped
44     protected $currentdata;  // Where we'll be acummulating data
46     public function __construct(array $paths = array()) {
47         $this->groupedpaths = array();
48         $this->currentdata = null;
49         parent::__construct($paths);
50     }
52     public function add_path($path, $grouped = false) {
53         if ($grouped) {
54             // Check there is no parent in the branch being grouped
55             if ($found = $this->grouped_parent_exists($path)) {
56                 $a = new stdclass();
57                 $a->path = $path;
58                 $a->parent = $found;
59                 throw new progressive_parser_exception('xml_grouped_parent_found', $a);
60             }
61             // Check there is no child in the branch being grouped
62             if ($found = $this->grouped_child_exists($path)) {
63                 $a = new stdclass();
64                 $a->path = $path;
65                 $a->child = $found;
66                 throw new progressive_parser_exception('xml_grouped_child_found', $a);
67             }
68             $this->groupedpaths[] = $path;
69         }
70         parent::add_path($path);
71     }
73     /**
74      * The parser fires this each time one path is going to be parsed
75      *
76      * @param string $path xml path which parsing has started
77      */
78     public function before_path($path) {
79         if ($this->path_is_grouped($path) and !isset($this->currentdata[$path])) {
80             // If the grouped element itself does not contain any final tags,
81             // we would not get any chunk data for it. So we add an artificial
82             // empty data chunk here that will be eventually replaced with
83             // real data later in {@link self::postprocess_chunk()}.
84             $this->currentdata[$path] = array(
85                 'path' => $path,
86                 'level' => substr_count($path, '/') + 1,
87                 'tags' => array(),
88             );
89         }
90         if (!$this->grouped_parent_exists($path)) {
91             parent::before_path($path);
92         }
93     }
95     /**
96      * The parser fires this each time one path has been parsed
97      *
98      * @param string $path xml path which parsing has ended
99      */
100     public function after_path($path) {
101         // Have finished one grouped path, dispatch it
102         if ($this->path_is_grouped($path)) {
103             // Any accumulated information must be in
104             // currentdata, properly built
105             $data = $this->currentdata[$path];
106             unset($this->currentdata[$path]);
107             // Always, before dispatching any chunk, send all pending start notifications.
108             $this->process_pending_startend_notifications($path, 'start');
109             // TODO: If running under DEBUG_DEVELOPER notice about >1MB grouped chunks
110             // And, finally, dispatch it.
111             $this->dispatch_chunk($data);
112         }
113         // Normal notification of path end
114         // Only if path is selected and not child of grouped
115         if (!$this->grouped_parent_exists($path)) {
116             parent::after_path($path);
117         }
118     }
120 // Protected API starts here
122     /**
123      * Override this method so grouping will be happening here
124      * also deciding between accumulating/dispatching
125      */
126     protected function postprocess_chunk($data) {
127         $path = $data['path'];
128         // If the chunk is a grouped one, simply put it into currentdata
129         if ($this->path_is_grouped($path)) {
130             $this->currentdata[$path] = $data;
132         // If the chunk is child of grouped one, add it to currentdata
133         } else if ($grouped = $this->grouped_parent_exists($path)) {
134             $this->build_currentdata($grouped, $data);
135             $this->chunks--; // not counted, as it's accumulated
137         // No grouped nor child of grouped, dispatch it
138         } else {
139             $this->dispatch_chunk($data);
140         }
141     }
143     protected function path_is_grouped($path) {
144         return in_array($path, $this->groupedpaths);
145     }
147     /**
148      * Function that will look for any grouped
149      * parent for the given path, returning it if found,
150      * false if not
151      */
152     protected function grouped_parent_exists($path) {
153         $parentpath = progressive_parser::dirname($path);
154         while ($parentpath != '/') {
155             if ($this->path_is_grouped($parentpath)) {
156                 return $parentpath;
157             }
158             $parentpath = progressive_parser::dirname($parentpath);
159         }
160         return false;
161     }
163     /**
164      * Function that will look for any grouped
165      * child for the given path, returning it if found,
166      * false if not
167      */
168     protected function grouped_child_exists($path) {
169         $childpath = $path . '/';
170         foreach ($this->groupedpaths as $groupedpath) {
171             if (strpos($groupedpath, $childpath) === 0) {
172                 return $groupedpath;
173             }
174         }
175         return false;
176     }
178     /**
179      * This function will accumulate the chunk into the specified
180      * grouped element for later dispatching once it is complete
181      */
182     protected function build_currentdata($grouped, $data) {
183         // Check the grouped already exists into currentdata
184         if (!is_array($this->currentdata) or !array_key_exists($grouped, $this->currentdata)) {
185             $a = new stdclass();
186             $a->grouped = $grouped;
187             $a->child = $data['path'];
188             throw new progressive_parser_exception('xml_cannot_add_to_grouped', $a);
189         }
190         $this->add_missing_sub($grouped, $data['path'], $data['tags']);
191     }
193     /**
194      * Add non-existing subarray elements
195      */
196     protected function add_missing_sub($grouped, $path, $tags) {
198         // Remember tag being processed
199         $processedtag = basename($path);
201         $info =& $this->currentdata[$grouped]['tags'];
202         $hierarchyarr = explode('/', str_replace($grouped . '/', '', $path));
204         $previouselement = '';
205         $currentpath = '';
207         foreach ($hierarchyarr as $index => $element) {
209             $currentpath = $currentpath . '/' . $element;
211             // If element is already set and it's not
212             // the processed one (with tags) fast move the $info
213             // pointer and continue
214             if ($element !== $processedtag && isset($info[$element])) {
215                 $previouselement = $element;
216                 $info =& $info[$element];
217                 continue;
218             }
220             // If previous element already has occurrences
221             // we move $info pointer there (only if last is
222             // numeric occurrence)
223             if (!empty($previouselement) && is_array($info) && count($info) > 0) {
224                 end($info);
225                 $key = key($info);
226                 if ((int) $key === $key) {
227                     $info =& $info[$key];
228                 }
229             }
231             // Create element if not defined
232             if (!isset($info[$element])) {
233                 // First into last element if present
234                 $info[$element] = array();
235             }
237             // If element is the current one, add information
238             if ($element === $processedtag) {
239                 $info[$element][] = $tags;
240             }
242             $previouselement = $element;
243             $info =& $info[$element];
244         }
245     }