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-2010 Zend Technologies USA Inc. (http://www.zend.com)
  19  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  20  * @version    $Id$
  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-2010 Zend Technologies USA Inc. (http://www.zend.com)
  39  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  40  */
  41 abstract 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 }