The Simons     Component Library

           

---

FileStream Class Reference

#include <FileStream.h>

Inheritance diagram for FileStream:

List of all members.

---

Detailed Description

FileStream: the abstract superclass of all file streams.

The FileStream class is an intermediate class in the streams hierarchy and the superclass of all streams that connect to an underlying filesystem. The descendants of FileStream are Input and Output, which implement ANSII standard C++ input and output filesystems and define the abstract protocols for reading and writing data files. FileStream manages the file path name common to all FileStreams and defines an optional locking protocol, whereby all FileStreams agree to access data files exclusively. FileStreams are initially closed when they are created. When opened, they connect to the underlying filesystem. When closed, they disconnect from the underlying filesystem. It is possible to test whether the connection to the filesystem was made; whether the FileStream is ready for the next I/O operation or failed the last one; and whether the FileStream is open for input, output or both. If the FileStream locking protocol is turned on, then FileStreams try to acquire exclusive locks on files before these are opened. The protocol is advisory, meaning that all client programs must agree to use the protocol to guarantee mutually exclusive file access.

Public Member Functions
	FileStream ()
	Construct a default FileStream.
	FileStream (StringID)
	Construct a FileStream onto a given path name.
virtual	~FileStream ()
	Release a FileStream.
virtual StringID	name () const
	Return the name of this FileStream.
virtual Boolean	log () const
	Test if this FileStream is a log.
virtual Void	openOn (StringID)
	Open this FileStream on a new pathname.
virtual Void	openLogOn (StringID)
	Open this FileStream as a log on a new pathname.
virtual Void	openLog ()
	Open this FileStream as a log file.
Static Public Member Functions
Void	setLocking (Boolean)
	Set the locking protocol for all files.
Protected Member Functions
	FileStream (const FileStream &)
	Copy another FileStream.
Boolean	acquireLock () const
	Acquire a lock on the file named by the path name.
Boolean	releaseLock () const
	Release a lock on the file named by the path name.
Void	fileNotFound () const
	Report that a file was not found.
Void	accessDenied () const
	Report that access to a file was denied.
Protected Attributes
StringID	pathName
	The file stream path name.
Static Protected Attributes
Boolean	locking = false
	The locking protocol flag.

---

Constructor & Destructor Documentation

FileStream::FileStream (  const FileStream &  stream  )  [protected]

Copy another FileStream. Required by C++ to ensure that copying a FileStream faithfully copies a Stream. Parameters: stream  - the FileStream to copy. Returns: the copied FileStream.

FileStream::FileStream (   )

Construct a default FileStream. The path name is set to null. When opened, this FileStream will connect to one of the standard input or output streams. Returns: an empty FileStream.

FileStream::FileStream (  StringID  path  )

Construct a FileStream onto a given path name. Sets the path name. When opened, this FileStream will connect to the filesystem named by the supplied path name. Parameters: path  - a path name.

FileStream::~FileStream (   )  [virtual]

Release a FileStream.

---

Member Function Documentation

Void FileStream::accessDenied (   )  const [protected]

Report that access to a file was denied. Provided for convenience, this method is inherited by all FileStreams and may be used to raise a DeviceBusy exception to signal that the FileStream attempted to connect to a filesystem, but the filesystem was already in use by some other FileStream. This happens either if the FileStream is already open on a different file, or if an attempt is made to open a locked file when the locking protocol is turned on.

Boolean FileStream::acquireLock (   )  const [protected]

Acquire a lock on the file named by the path name. If the FileStream locking protocol is turned on, this method is called by subclasses before they open a file, to guarantee that they acquire exclusive access to that file. A file lock is indicated by creating a special lockfile in the same directory as the data file, with the ".lok" extension. If the lockfile already exists, no other stream may open the data file. If the FileStream is a standard stream, "Standard.lok" will be created. Returns: true, if the lock was acquired; false if it was denied.

Void FileStream::fileNotFound (   )  const [protected]

Report that a file was not found. Provided for convenience, this method is inherited by all FileStreams and may be used to raise a NotFound exception to signal that the FileStream attempted to connect to a filesystem, but the filesystem was not found. Usually, this is because an incorrect file path name was used.

Boolean FileStream::log (   )  const [virtual]

Test if this FileStream is a log. Use this method to test if data written to this FileStream is being appended to existing data, rather than overwriting existing data. Returns: true if this FileStream is a log, otherwise false. Reimplemented in Output.

StringID FileStream::name (   )  const [virtual]

Return the name of this FileStream. If a String name was supplied as the file path name, return this as the stream name. Otherwise, detect which of the standard streams this FileStream is connected to and return one of "Standard Input", "Standard Output" or "Standard Error". Reimplemented from Stream.

Void FileStream::openLog (   )  [virtual]

Open this FileStream as a log file. Reconnect this FileStream with its underlying filesystem and open for appending new data to existing data. This method is abstract. It is redefined in descendants of FileStream that allow output to log files. Reimplemented in Output, and WebOutput.

Void FileStream::openLogOn (  StringID  path  )  [virtual]

Open this FileStream as a log on a new pathname. Provided this FileStream is closed, sets the new path name and opens a connection to the underlying filesystem. Otherwise, raises a DeviceBusy exception, to indicate that this FileStream is already connected to another filesystem. Use openLogOn() and close() alternately to connect to a series of different log files. Parameters: path  - a file path name. Reimplemented in WebOutput.

Void FileStream::openOn (  StringID  path  )  [virtual]

Open this FileStream on a new pathname. Provided this FileStream is closed, sets the new path name and opens a connection to the underlying filesystem. Otherwise, raises a DeviceBusy exception, to indicate that this FileStream is already connected to another filesystem. Use openOn() and close() alternately to connect to a series of different files. Parameters: path  - a file path name. Reimplemented from Stream. Reimplemented in WebOutput.

Boolean FileStream::releaseLock (   )  const [protected]

Release a lock on the file named by the path name. If the FileStream locking protocol is turned on, this method is called by subclasses after they close a file, to guarantee that they release exclusive access to that file. Releasing a lock is indicated by deleting a special lockfile in the same directory as the data file, with the ".lok" extension. If the FileStream is a standard stream, this is "Standard.lok". Once the lockfile no longer exists, other streams may access the data file. Returns: true, to indicate successful release of the lock.

Void FileStream::setLocking (  Boolean  setting  )  [inline, static]

Set the locking protocol for all files. When set to false, no locking protocol is applied. When set to true, an exclusive locking protocol is applied both for read and write access. The default is false, which allows multiple streams to open the same file for reading and writing, which may have unforeseen results. When exclusive locking is enabled, only one stream may access a file at a time. If multiple processes are involved, this is an advisory protocol, meaning that both processes must agree to use the locking protocol. Parameters: setting  - true means "turned on" and false means "turned off".

---

Member Data Documentation

Boolean FileStream::locking = false [static, protected]

The locking protocol flag.

StringID FileStream::pathName [protected]

The file stream path name.

---

The documentation for this class was generated from the following files:

• FileStream.h
• Basic.cc
• FileStream.cc

---