MDL-35603 - Backup - Course import selector notice
[moodle.git] / backup / util / xml / output / xml_output.class.php
CommitLineData
69dd0c8c
EL
1<?php
2
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/>.
17
18/**
19 * @package moodlecore
20 * @subpackage backup-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 */
24
25/**
26 * This abstract class outputs XML contents provided by @xml_writer
27 *
28 * Contains the common functionalities for all the xml_output_xxx classes
29 * and the interface for them. Mainly it's in charge of:
30 * - Initialize the corresponding stream/handler (file, DB connection...)
31 * - Finalize the stream/handler
32 * - Provide one common buffer for all output implementations
33 * - Receive XML contents from the @xml_writer and output them
34 * - Some basic throughtput stats
35 *
36 * TODO: Finish phpdocs
37 */
38abstract class xml_output {
39
40 const DEFAULT_BUFFER_SIZE = 4096; // Use a default buffer size of 4K
41
42 protected $inittime; // Initial microtime
43 protected $sentbytes; // Bytes sent to output
44
45 protected $usebuffer; // Boolean to specify if output supports buffer (true) or no (false)
46 protected $buffersize;// Size, in bytes, of the buffer.
47 protected $currentbuffer; // Buffer contents
48 protected $currentbuffersize;// Current buffer size
49
50 protected $running; // To know if output is running
51
52 public function __construct($usebuffer = true) {
53 $this->inittime = microtime(true);
0e35ba6f 54 $this->finishtime = $this->inittime;
69dd0c8c
EL
55 $this->sentbytes = 0;
56
57 $this->usebuffer = $usebuffer;
58 $this->buffersize = $this->usebuffer ? self::DEFAULT_BUFFER_SIZE : 0;
59
60 $this->running = null;
61 }
62
63 public function set_buffersize($buffersize) {
64 if ($this->running) {
65 throw new xml_output_exception('xml_output_already_started');
66 }
67 if (!$this->usebuffer) {
68 throw new xml_output_exception('xml_output_buffer_nosupport');
69 }
70 // TODO: check it is integer > 0
71 $this->buffersize = $buffersize;
72 }
73
74 public function start() {
75 if ($this->running === true) {
76 throw new xml_output_exception('xml_output_already_started');
77 }
78 if ($this->running === false) {
79 throw new xml_output_exception('xml_output_already_stopped');
80 }
81 $this->inittime = microtime(true);
82 $this->sentbytes = 0;
83 $this->running = true;
84 $this->currentbuffer = '';
85 $this->currentbuffersize = 0;
86 $this->init();
87 }
88
89 public function stop() {
90 if (!$this->running) {
91 throw new xml_output_exception('xml_output_not_started');
92 }
93 $this->finishtime = microtime(true);
94 if ($this->usebuffer && $this->currentbuffersize > 0) { // Have pending contents in buffer
95 $this->send($this->currentbuffer); // Send them
96 $this->currentbuffer = '';
97 $this->currentbuffersize = 0;
98 }
99 $this->running = false;
100 $this->finish();
101 }
102
103 /**
104 * Get contents from @xml_writer and buffer/output them
105 */
106 public function write($content) {
107 if (!$this->running) {
108 throw new xml_output_exception('xml_output_not_started');
109 }
110 $lenc = strlen($content); // Get length in bytes
111 if ($lenc == 0) { // 0 length contents, nothing to do
112 return;
113 }
114 // Buffer handling if available
115 $tooutput = true; // By default, perform output
116 if ($this->usebuffer) { // Buffer
117 $this->currentbuffer .= $content;
118 $this->currentbuffersize += $lenc;
119 if ($this->currentbuffersize < $this->buffersize) {
120 $tooutput = false; // Still within the buffer, don't output
121 } else {
122 $content = $this->currentbuffer; // Prepare for output
123 $lenc = $this->currentbuffersize;
124 $this->currentbuffer = '';
125 $this->currentbuffersize = 0;
126 }
127 }
128 // Output
129 if ($tooutput) {
130 $this->send($content); // Efectively send the contents
131 $this->sentbytes += $lenc;
132 }
133 }
134
135 public function debug_info() {
136 if ($this->running !== false) {
137 throw new xml_output_exception('xml_output_not_stopped');
138 }
139 return array('memory' => memory_get_peak_usage(true),
140 'time' => $this->finishtime - $this->inittime,
141 'sent' => $this->sentbytes);
142 }
143
144// Implementable API starts here
145
146 abstract protected function init();
147
148 abstract protected function finish();
149
150 abstract protected function send($content);
151}
152
153/*
154 * Exception class used by all the @xml_output stuff
155 */
156class xml_output_exception extends moodle_exception {
157
158 public function __construct($errorcode, $a=NULL, $debuginfo=null) {
159 parent::__construct($errorcode, 'error', '', $a, null, $debuginfo);
160 }
161}