13.12. Storage API

An abstract class ZSearchDirectory defines directory functionality.

The ZSearch constructor uses either a string or ZSearchDirectory object as an input.

ZSearchDirectoryFilesystem class implements directory functionality for file system.

If string is used as an input for the ZSearch constructor, then the index reader (ZSearch object) treats it as a file system path and instantiates ZSearchDirectoryFilesystem object by themselves.

You can define your own directory implementation by extending ZSearchDirectory class.

ZSearchDirectory methods:

abstract class ZSearchDirectory {
    /**
     * Closes the store.
     *
     * @return void
     */
    abstract function close();


    /**
     * Creates a new, empty file in the directory with the given $filename.
     *
     * @param string $name
     * @return void
     */
    abstract function createFile($filename);


    /**
     * Removes an existing $filename in the directory.
     *
     * @param string $filename
     * @return void
     */
    abstract function deleteFile($filename);


    /**
     * Returns true if a file with the given $filename exists.
     *
     * @param string $filename
     * @return boolean
     */
    abstract function fileExists($filename);


    /**
     * Returns the length of a $filename in the directory.
     *
     * @param string $filename
     * @return integer
     */
    abstract function fileLength($filename);


    /**
     * Returns the UNIX timestamp $filename was last modified.
     *
     * @param string $filename
     * @return integer
     */
    abstract function fileModified($filename);


    /**
     * Renames an existing file in the directory.
     *
     * @param string $from
     * @param string $to
     * @return void
     */
    abstract function renameFile($from, $to);


    /**
     * Sets the modified time of $filename to now.
     *
     * @param string $filename
     * @return void
     */
    abstract function touchFile($filename);


    /**
     * Returns a ZSearchFile object for a given $filename in the directory.
     *
     * @param string $filename
     * @return ZSearchFile
     */
    abstract function getFileObject($filename);

}
    

getFileObject($filename) method of ZSearchDirectory class returns ZSearchFile object.

ZSearchFile abstract class implements file abstraction and index file reading primitives.

You must also extend ZSearchFile class for your Directory implementation.

Only two methods of ZSearchFile class must be overloaded in your implementation:

class MyZSearchFile extends ZSearchFile {
    /**
     * Sets the file position indicator and advances the file pointer.
     * The new position, measured in bytes from the beginning of the file,
     * is obtained by adding offset to the position specified by whence,
     * whose values are defined as follows:
     * SEEK_SET - Set position equal to offset bytes.
     * SEEK_CUR - Set position to current location plus offset.
     * SEEK_END - Set position to end-of-file plus offset. (To move to
     * a position before the end-of-file, you need to pass a negative value
     * in offset.)
     * Upon success, returns 0; otherwise, returns -1
     *
     * @param integer $offset
     * @param integer $whence
     * @return integer
     */
    public function seek($offset, $whence=SEEK_SET) {
        ...
    }

    /**
     * Read a $length bytes from the file and advance the file pointer.
     *
     * @param integer $length
     * @return string
     */
    protected function _fread($length=1) {
        ...
    }