Added abstraction classes for file-based stacks and index files, some setter
[core.git] / inc / classes / main / file_directories / class_BaseFileIo.php
1 <?php
2 /**
3  * A general FileIo class
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.ship-simu.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23  */
24 class BaseFileIo extends BaseFrameworkSystem {
25         /**
26          * The current file we are working in
27          */
28         private $fileName = '';
29
30         /**
31          * The file pointer
32          */
33         private $filePointer = NULL;
34
35         /**
36          * Protected constructor
37          *
38          * @param       $className      Name of the class
39          * @return      void
40          */
41         protected function __construct ($className) {
42                 // Call parent constructor
43                 parent::__construct($className);
44         }
45
46         /**
47          * Destructor for cleaning purposes, etc
48          *
49          * @return      void
50          */
51         public final function __destruct() {
52                 // Is there a resource pointer? Then we have to close the file here!
53                 if (is_resource($this->getPointer())) {
54                         // Try to close a file
55                         $this->closeFile();
56                 } // END - if
57
58                 // Call the parent destructor
59                 parent::__destruct();
60         }
61
62         /**
63          * Close a file source and set it's instance to null and the file name
64          * to empty
65          *
66          * @return      void
67          * @throws      NullPointerException    If the file pointer instance
68          *                                                                      is not set by setPointer()
69          * @throws      InvalidResourceException        If there is being set
70          */
71         public function closeFile () {
72                 if (is_null($this->getPointer())) {
73                         // Pointer not initialized
74                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
75                 } elseif (!is_resource($this->getPointer())) {
76                         // Pointer is not a valid resource!
77                         throw new InvalidResourceException($this, self::EXCEPTION_INVALID_RESOURCE);
78                 }
79
80                 // Close the file pointer and reset the instance variable
81                 @fclose($this->getPointer());
82                 $this->setPointer(NULL);
83                 $this->setFileName('');
84         }
85
86         /**
87          * Setter for the file pointer
88          *
89          * @param       $filePointer    File resource
90          * @return      void
91          */
92         protected final function setPointer ($filePointer) {
93                 $this->filePointer = $filePointer;
94         }
95
96         /**
97          * Getter for the file pointer
98          *
99          * @return      $filePointer    The file pointer which shall be a valid
100          *                                                      file resource
101          */
102         public final function getPointer () {
103                 return $this->filePointer;
104         }
105
106         /**
107          * Setter for file name
108          *
109          * @param       $fileName       The new file name
110          * @return      void
111          */
112         protected final function setFileName ($fileName) {
113                 $fileName = (string) $fileName;
114                 $this->fileName = $fileName;
115         }
116
117         /**
118          * Getter for file name
119          *
120          * @return      $fileName       The current file name
121          */
122         public final function getFileName () {
123                 return $this->fileName;
124         }
125
126         /**
127          * Determines seek position
128          *
129          * @return      $seekPosition   Current seek position
130          */
131         public final function determineSeekPosition () {
132                 return ftell($this->getPointer());
133         }
134
135         /**
136          * Seek to given offset (default) or other possibilities as fseek() gives.
137          *
138          * @param       $offset         Offset to seek to (or used as "base" for other seeks)
139          * @param       $whence         Added to offset (default: only use offset to seek to)
140          * @return      $status         Status of file seek: 0 = success, -1 = failed
141          */
142         public function seek ($offset, $whence = SEEK_SET) {
143                 // Seek to position
144                 $status = fseek($this->getPointer(), $offset, $whence);
145
146                 // Return status
147                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] status=%d', __METHOD__, __LINE__, $status));
148                 return $status;
149         }
150
151         /**
152          * Size of this file
153          *
154          * @return      $size   Size (in bytes) of file
155          * @todo        Handle seekStatus
156          */
157         public function size () {
158                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
159
160                 // Get current seek position
161                 $seekPosition = $this->determineSeekPosition();
162
163                 // Seek to end
164                 $seekStatus = $this->seek(0, SEEK_END);
165                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] seekStatus=%d', __METHOD__, __LINE__, $seekStatus));
166
167                 // Get position again  (which is the end of the file)
168                 $size = $this->determineSeekPosition();
169
170                 // Reset seek position to old
171                 $this->seek($seekPosition);
172
173                 // Return size
174                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d:] size=%s - EXIT!', __METHOD__, __LINE__, $size));
175                 return $size;
176         }
177 }
178
179 // [EOF]
180 ?>