/library/Zend/Pdf/FileParserDataSource.php

  1<?php
  2/**
  3 * Zend Framework
  4 *
  5 * LICENSE
  6 *
  7 * This source file is subject to the new BSD license that is bundled
  8 * with this package in the file LICENSE.txt.
  9 * It is also available through the world-wide-web at this URL:
 10 * http://framework.zend.com/license/new-bsd
 11 * If you did not receive a copy of the license and are unable to
 12 * obtain it through the world-wide-web, please send an email
 13 * to license@zend.com so we can send you a copy immediately.
 14 *
 15 * @category   Zend
 16 * @package    Zend_Pdf
 17 * @subpackage FileParser
 18 * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
 19 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 20 * @version    $Id: FileParserDataSource.php 24594 2012-01-05 21:27:01Z matthew $
 21 */
 22
 23/**
 24 * Abstract helper class for {@link Zend_Pdf_FileParser} that provides the
 25 * data source for parsing.
 26 *
 27 * Concrete subclasses allow for parsing of in-memory, filesystem, and other
 28 * sources through a common API. These subclasses also take care of error
 29 * handling and other mundane tasks.
 30 *
 31 * Subclasses must implement at minimum {@link __construct()},
 32 * {@link __destruct()}, {@link readBytes()}, and {@link readAllBytes()}.
 33 * Subclasses should also override {@link moveToOffset()} and
 34 * {@link __toString()} as appropriate.
 35 *
 36 * @package    Zend_Pdf
 37 * @subpackage FileParser
 38 * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
 39 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 40 */
 41abstract class Zend_Pdf_FileParserDataSource
 42{
 43  /**** Instance Variables ****/
 44
 45
 46    /**
 47     * Total size in bytes of the data source.
 48     * @var integer
 49     */
 50    protected $_size = 0;
 51
 52    /**
 53     * Byte offset of the current read position within the data source.
 54     * @var integer
 55     */
 56    protected $_offset = 0;
 57
 58
 59
 60  /**** Public Interface ****/
 61
 62
 63  /* Abstract Methods */
 64
 65    /**
 66     * Object constructor. Opens the data source for parsing.
 67     *
 68     * Must set $this->_size to the total size in bytes of the data source.
 69     *
 70     * Upon return the data source can be interrogated using the primitive
 71     * methods described here.
 72     *
 73     * If the data source cannot be opened for any reason (such as insufficient
 74     * permissions, missing file, etc.), will throw an appropriate exception.
 75     *
 76     * @throws Zend_Pdf_Exception
 77     */
 78    abstract public function __construct();
 79
 80    /**
 81     * Object destructor. Closes the data source.
 82     *
 83     * May also perform cleanup tasks such as deleting temporary files.
 84     */
 85    abstract public function __destruct();
 86
 87    /**
 88     * Returns the specified number of raw bytes from the data source at the
 89     * byte offset of the current read position.
 90     *
 91     * Must advance the read position by the number of bytes read by updating
 92     * $this->_offset.
 93     *
 94     * Throws an exception if there is insufficient data to completely fulfill
 95     * the request or if an error occurs.
 96     *
 97     * @param integer $byteCount Number of bytes to read.
 98     * @return string
 99     * @throws Zend_Pdf_Exception
100     */
101    abstract public function readBytes($byteCount);
102
103    /**
104     * Returns the entire contents of the data source as a string.
105     *
106     * This method may be called at any time and so must preserve the byte
107     * offset of the read position, both through $this->_offset and whatever
108     * other additional pointers (such as the seek position of a file pointer)
109     * that might be used.
110     *
111     * @return string
112     */
113    abstract public function readAllBytes();
114
115
116  /* Object Magic Methods */
117
118    /**
119     * Returns a description of the object for debugging purposes.
120     *
121     * Subclasses should override this method to provide a more specific
122     * description of the actual object being represented.
123     *
124     * @return string
125     */
126    public function __toString()
127    {
128        return get_class($this);
129    }
130
131
132  /* Accessors */
133
134    /**
135     * Returns the byte offset of the current read position within the data
136     * source.
137     *
138     * @return integer
139     */
140    public function getOffset()
141    {
142        return $this->_offset;
143    }
144
145    /**
146     * Returns the total size in bytes of the data source.
147     *
148     * @return integer
149     */
150    public function getSize()
151    {
152        return $this->_size;
153    }
154
155
156  /* Primitive Methods */
157
158    /**
159     * Moves the current read position to the specified byte offset.
160     *
161     * Throws an exception you attempt to move before the beginning or beyond
162     * the end of the data source.
163     *
164     * If a subclass needs to perform additional tasks (such as performing a
165     * fseek() on a filesystem source), it should do so after calling this
166     * parent method.
167     *
168     * @param integer $offset Destination byte offset.
169     * @throws Zend_Pdf_Exception
170     */
171    public function moveToOffset($offset)
172    {
173        if ($this->_offset == $offset) {
174            return;    // Not moving; do nothing.
175        }
176        if ($offset < 0) {
177            require_once 'Zend/Pdf/Exception.php';
178            throw new Zend_Pdf_Exception('Attempt to move before start of data source',
179                                         Zend_Pdf_Exception::MOVE_BEFORE_START_OF_FILE);
180        }
181        if ($offset >= $this->_size) {    // Offsets are zero-based.
182            require_once 'Zend/Pdf/Exception.php';
183            throw new Zend_Pdf_Exception('Attempt to move beyond end of data source',
184                                         Zend_Pdf_Exception::MOVE_BEYOND_END_OF_FILE);
185        }
186        $this->_offset = $offset;
187    }
188
189    /**
190     * Shifts the current read position within the data source by the specified
191     * number of bytes.
192     *
193     * You may move forward (positive numbers) or backward (negative numbers).
194     * Throws an exception you attempt to move before the beginning or beyond
195     * the end of the data source.
196     *
197     * @param integer $byteCount Number of bytes to skip.
198     * @throws Zend_Pdf_Exception
199     */
200    public function skipBytes($byteCount)
201    {
202        $this->moveToOffset($this->_offset + $byteCount);
203    }
204}