AMOS::BankStream_t Class Reference

Provides stream functionality for an AMOS data bank. More...

#include <BankStream_AMOS.hh>

Inheritance diagram for AMOS::BankStream_t:

[legend]Collaboration diagram for AMOS::BankStream_t:

[legend]List of all members.


Public Types
enum	bankseekdir { BEGIN, CURR, END }
Public Member Functions
	BankStream_t (NCode_t type)
	Constructs an empty BankStream_t of objects with a certain NCode.
	~BankStream_t ()
void	clear ()
	Clears a bank by erasing all it's objects and its ID map.
void	close ()
	Closes a bank on disk.
void	create (const std::string &dir, BankMode_t mode=B_READ\|B_WRITE)
	Forcibly creates and opens a bank on disk.
void	destroy ()
	Closes and removes a bank from disk.
bool	empty () const
	Returns true if bank is empty.
bool	eof () const
	Checks if the end of stream flag has been set.
bool	exists (const std::string &dir)
bool	existsEID (const std::string &eid) const
	Returns true if EID exists in the bank.
bool	existsIID (ID_t iid) const
	Returns true if IID exists in the bank.
const IDMap_t &	getIDMap () const
	Get the current (IID <-> EID) -> BID map for the bank.
Size_t	getIDMapSize () const
	Get the number of objects in the Bank with and IID or EID.
ID_t	getMaxIID () const
	Searches through the bank for the largest IID.
Size_t	getSize () const
	Get the size of the bank, i.e. the number of stored records.
signed char	getStatus () const
	Get the bank status.
NCode_t	getType () const
	Get the unique bank type identifier.
BankStream_t &	ignore (bankstreamoff n)
	Ignores the next n stream objects.
bool	isOpen () const
	Check the bank's open status.
ID_t	lookupBID (ID_t iid) const
	Converts an IID to a BID, throw exception on failure.
ID_t	lookupBID (const std::string &eid) const
	Converts an EID to a BID, throw exception on failure.
const std::string &	lookupEID (ID_t iid) const
	Converts an IID to an EID.
ID_t	lookupIID (const std::string &eid) const
	Converts an EID to an IID.
void	open (const std::string &dir, BankMode_t mode=B_READ\|B_WRITE)
	Opens a bank on disk.
BankStream_t &	seekg (bankstreamoff off, bankseekdir dir)
	Seeks to a different position in the BankStream.
BankStream_t &	seekg (ID_t pos)
	Seeks to a different position in the BankStream.
void	setStatus (signed char status)
	Set the bank status.
ID_t	tellg ()
	Return the current position of the get pointer.
ID_t	tellp ()
	Return the current position of the put pointer.
	operator bool () const
	Cast the BankStream to a bool reflecting the state of !eof().
bool	operator! () const
	Evaluate eof() and return.
BankStream_t &	operator>> (IBankable_t &obj)
	Fetch the next object in the BankStream.
BankStream_t &	operator<< (IBankable_t &obj)
	Append a new object to the BankStream.
Protected Member Functions
void	init ()
	Initializes bank variables.
bool	inrange ()
Protected Attributes
bool	eof_m
	eof error flag
ID_t	curr_bid_m
	BID to be returned on next get.
std::vector< const IDMap_t::HashTriple_t * >	triples_m
	BID,EID,IID map.
Static Protected Attributes
const Size_t	DEFAULT_BUFFER_SIZE = 1024
	IO buffer size.
const Size_t	MAX_OPEN_PARTITIONS = 2
	Allowable simultaneously open partitions (one for >>, one for <<).

Detailed Description

Provides stream functionality for an AMOS data bank.

Allows input and output streaming of an AMOS data bank. This provides a way to iterate through object without IID or EID tags, since every object in the bank will be streamed in order regardless of its IDs. It is assumed that this class will be used to stream many consecutive objects, thus certain optimizations are made for this use case. For random access and frequent switches between fetch and append operations, the Bank_t class is more efficient. For fetching every object in a bank in order, or writing a large number of objects to a bank, this class is more efficient.

Definition at line 34 of file BankStream_AMOS.hh.

Member Enumeration Documentation

enum AMOS::BankStream_t::bankseekdir

Enumeration values:

BEGIN

CURR

END

Definition at line 69 of file BankStream_AMOS.hh.

Constructor & Destructor Documentation

AMOS::BankStream_t::BankStream_t ( NCode_t type ) [inline]

Constructs an empty BankStream_t of objects with a certain NCode.
Initializes members and sets BankStream type to the supplied value. All future operations on this bank must be made with a Bankable type that is compatibile with the supplied NCode.
Once a BankStream is created with a certain NCode, only objects compatible with that NCode can be used with that Bank. For instance, if a BankStream is constructed with 'BankStream_t mybank (Read::NCODE);', only Read_t objects could be used with mybank. Also, if a static NCode member is not available 'BankStream_t mybank (Encode("RED"));' will also work.

Parameters:

type The type of Bank to construct

Definition at line 93 of file BankStream_AMOS.hh.
References DEFAULT_BUFFER_SIZE, init(), MAX_OPEN_PARTITIONS, AMOS::NCode_t, AMOS::NULL_ID, and triples_m.

AMOS::BankStream_t::~BankStream_t ( ) [inline]

Definition at line 104 of file BankStream_AMOS.hh.
References close().

Member Function Documentation

void AMOS::BankStream_t::clear ( ) [inline]

Clears a bank by erasing all it's objects and its ID map.
Erases all the objects in a bank, but keeps the bank open at the current location. Only throws an exception if the bank is not open for writing. Won't complain if some of the partitions won't unlink etc. Has no effect on a closed bank.

Precondition:
The bank is open for writing

Exceptions:

IOException_t

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 112 of file BankStream_AMOS.hh.
References AMOS::Bank_t::clear(), and init().

void AMOS::BankStream_t::close ( ) [inline]

Closes a bank on disk.
Flushes all files, closes all files and re-initializes members. Has no effect on a closed bank.

Exceptions:

IOException_t

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 120 of file BankStream_AMOS.hh.
References AMOS::Bank_t::close(), and init().
Referenced by ~BankStream_t().

void AMOS::BankStream_t::create ( const std::string & dir,

BankMode_t mode = B_READ|B_WRITE

) [inline]

Forcibly creates and opens a bank on disk.
Forcibly creates and opens a bank. Any pre-existing bank of this type will be destroyed and any conflicting files will be overwritten if permissions allow. If you wish not to overwrite an existing bank, use the exists method to first check for a conflicting bank of this type. An open bank will first be closed before the new one is created.

Parameters:

dir The directory in which to create the bank

mode The mode of the bank (B_READ | B_WRITE)

Precondition:
mode includes B_WRITE
sufficient read/write/exe permissions for dir and bank files

Exceptions:

IOException_t

ArgumentException_t

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 128 of file BankStream_AMOS.hh.
References AMOS::BankMode_t, AMOS::Bank_t::create(), and init().

void AMOS::BankStream_t::destroy ( ) [inline]

Closes and removes a bank from disk.
Closes the bank and unlinks all files and empty directories. Only throws an exception if the bank is not open for writing. Won't complain if some of the partitions won't unlink etc.

Precondition:
The bank is open for writing

Exceptions:

IOException_t

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 136 of file BankStream_AMOS.hh.
References AMOS::Bank_t::destroy(), and init().

bool AMOS::BankStream_t::empty ( ) const [inline]

Returns true if bank is empty.

Reimplemented from AMOS::Bank_t.
Definition at line 144 of file BankStream_AMOS.hh.
References AMOS::Bank_t::empty().

bool AMOS::BankStream_t::eof ( ) const [inline]

Checks if the end of stream flag has been set.
Returns true if a previous IO operation set the end of stream flag, returns false if there have been no previous end of stream failures. The eof flag only applies to fetch operations, append operations will never raise the eof flag. Will return true if bank is closed.

Returns:
true if eof flag has been set, false otherwise
Definition at line 157 of file BankStream_AMOS.hh.
References eof_m.
Referenced by operator bool(), operator!(), and operator>>().

bool AMOS::BankStream_t::exists ( const std::string & dir ) [inline]

Definition at line 164 of file BankStream_AMOS.hh.
References AMOS::Bank_t::exists().

bool AMOS::BankStream_t::existsEID ( const std::string & eid ) const [inline]

Returns true if EID exists in the bank.

Reimplemented from AMOS::Bank_t.
Definition at line 168 of file BankStream_AMOS.hh.
References AMOS::Bank_t::existsEID().

bool AMOS::BankStream_t::existsIID ( ID_t iid ) const [inline]

Returns true if IID exists in the bank.

Reimplemented from AMOS::Bank_t.
Definition at line 173 of file BankStream_AMOS.hh.
References AMOS::Bank_t::existsIID(), and AMOS::ID_t.

const IDMap_t& AMOS::BankStream_t::getIDMap ( ) const [inline]

Get the current (IID <-> EID) -> BID map for the bank.
Access to the bank's IDMap. One may iterate through the IDMap for a list of IDs in the bank. Users may not however directly modify the IDMap, because the bank will automatically update the IDMap based on the IDs of the objects appended to it. See IDMap_t API for more available methods.

Returns:
A const reference to the bank's IDMap

Reimplemented from AMOS::Bank_t.
Definition at line 177 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getIDMap().
Referenced by open().

Size_t AMOS::BankStream_t::getIDMapSize ( ) const [inline]

Get the number of objects in the Bank with and IID or EID.
Returns the total number of ID'ed objects stored in the bank. This number only includes object which have an associated IID or EID. Use getSize() to get the total number of objects in the bank.

Returns:
The number of ID'ed objects stored in the bank

Reimplemented from AMOS::Bank_t.
Definition at line 181 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getIDMapSize(), and AMOS::Size_t.

ID_t AMOS::BankStream_t::getMaxIID ( ) const [inline]

Searches through the bank for the largest IID.

Note:
O(n) time complexity

Returns:
The maximum IID in the bank

Reimplemented from AMOS::Bank_t.
Definition at line 185 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getMaxIID(), and AMOS::ID_t.

Size_t AMOS::BankStream_t::getSize ( ) const [inline]

Get the size of the bank, i.e. the number of stored records.
This method returns the total number of objects stored in the bank, including anonymous objects which have no associated IID or EID.

Returns:
The size of the bank, or 0 if the bank is empty

Reimplemented from AMOS::Bank_t.
Definition at line 189 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getSize(), and AMOS::Size_t.

signed char AMOS::BankStream_t::getStatus ( ) const [inline]

Get the bank status.
Currently the status is set by the user and not written to the bank. So don't expect any interesting return values from this method. Status is set to zero on object initialization and then left untouched.

Returns:
Return the status of the bank

Reimplemented from AMOS::Bank_t.
Definition at line 193 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getStatus().

NCode_t AMOS::BankStream_t::getType ( ) const [inline]

Get the unique bank type identifier.
Is equivalent to the NCode of the objects stored in the bank.

Returns:
The unique bank type identifier

Reimplemented from AMOS::Bank_t.
Definition at line 197 of file BankStream_AMOS.hh.
References AMOS::Bank_t::getType(), and AMOS::NCode_t.

BankStream_t & BankStream_t::ignore ( bankstreamoff n )

Ignores the next n stream objects.
Only slightly more efficient than fetching n records. Seeking past the end of stream will set the eof flag.

Precondition:
The bank is open for reading

Parameters:

n The number of objects to skip in the stream

Exceptions:

IOException_t

Returns:
The updated BankStream
Definition at line 23 of file BankStream_AMOS.cc.
References AMOS_THROW_IO, AMOS::B_READ, curr_bid_m, eof_m, AMOS::ID_t, inrange(), AMOS::Bank_t::localizeBID(), AMOS::readLE(), seekg(), AMOS::Size_t, and tellg().
Referenced by operator>>(), and seekg().

void AMOS::BankStream_t::init ( ) [inline, protected]

Initializes bank variables.

Reimplemented from AMOS::Bank_t.
Definition at line 47 of file BankStream_AMOS.hh.
References curr_bid_m, eof_m, and triples_m.
Referenced by BankStream_t(), clear(), close(), create(), destroy(), and open().

bool AMOS::BankStream_t::inrange ( ) [inline, protected]

Definition at line 56 of file BankStream_AMOS.hh.
References curr_bid_m.
Referenced by ignore(), operator>>(), and seekg().

bool AMOS::BankStream_t::isOpen ( ) const [inline]

Check the bank's open status.

Returns:
true if open, false if closed

Reimplemented from AMOS::Bank_t.
Definition at line 215 of file BankStream_AMOS.hh.
References AMOS::Bank_t::isOpen().

ID_t AMOS::BankStream_t::lookupBID ( const std::string & eid ) const [inline]

Converts an EID to a BID, throw exception on failure.

Exceptions:

ArgumentException_t

Returns:
The BID of the specified EID

Reimplemented from AMOS::Bank_t.
Definition at line 224 of file BankStream_AMOS.hh.
References AMOS::ID_t, and AMOS::Bank_t::lookupBID().

ID_t AMOS::BankStream_t::lookupBID ( ID_t iid ) const [inline]

Converts an IID to a BID, throw exception on failure.

Exceptions:

ArgumentException_t

Returns:
The BID of the specified IID

Reimplemented from AMOS::Bank_t.
Definition at line 219 of file BankStream_AMOS.hh.
References AMOS::ID_t, and AMOS::Bank_t::lookupBID().

const std::string& AMOS::BankStream_t::lookupEID ( ID_t iid ) const [inline]

Converts an IID to an EID.

Returns:
Returns the EID of the IID or empty string on failure

Reimplemented from AMOS::Bank_t.
Definition at line 229 of file BankStream_AMOS.hh.
References AMOS::ID_t, and AMOS::Bank_t::lookupEID().

ID_t AMOS::BankStream_t::lookupIID ( const std::string & eid ) const [inline]

Converts an EID to an IID.

Returns:
Returns the IID of the EID or NULL_ID on failure

Reimplemented from AMOS::Bank_t.
Definition at line 234 of file BankStream_AMOS.hh.
References AMOS::ID_t, and AMOS::Bank_t::lookupIID().

void BankStream_t::open ( const std::string & dir,

BankMode_t mode = B_READ|B_WRITE

)

Opens a bank on disk.
Opens a bank on disk, allowing modification/access operations like append and fetch to be performed. An open bank will first be closed before the new one is opened. Check for the existence of a bank (with the exists method) before opening to avoid an exception. If the B_SPY mode is activated, only read access to the banks is required, otherwise both read and write access is required.

Parameters:

dir The resident directory of the bank

mode The mode of the bank (B_READ | B_WRITE | B_SPY)

Precondition:
At least one of the modes is specified
The specified directory contains a bank of this type
sufficient read/write/exe permissions for dir and bank files

Exceptions:

IOException_t

ArgumentException_t

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 57 of file BankStream_AMOS.cc.
References AMOS::BankMode_t, getIDMap(), init(), AMOS::Bank_t::open(), and triples_m.

AMOS::BankStream_t::operator bool ( ) const [inline]

Cast the BankStream to a bool reflecting the state of !eof().

Returns:
The evaluation of !eof()
Definition at line 334 of file BankStream_AMOS.hh.
References eof().

bool AMOS::BankStream_t::operator! ( ) const [inline]

Evaluate eof() and return.

Returns:
The evaluation of eof()
Definition at line 345 of file BankStream_AMOS.hh.
References eof().

BankStream_t & BankStream_t::operator<< ( IBankable_t & obj )

Append a new object to the BankStream.

Precondition:
The bank is open for writing
obj is compatible with the banktype

Exceptions:

ArgumentException_t

IOException_t

Returns:
The modified BankStream
Definition at line 137 of file BankStream_AMOS.cc.
References AMOS::Bank_t::addPartition(), AMOS_THROW_ARGUMENT, AMOS_THROW_IO, AMOS::B_WRITE, AMOS::Bank_t::getLastPartition(), AMOS::IBankable_t::getNCode(), AMOS::Bank_t::remove(), AMOS::Size_t, tellp(), triples_m, and AMOS::writeLE().

BankStream_t & BankStream_t::operator>> ( IBankable_t & obj )

Fetch the next object in the BankStream.
If the operation fails, obj will be unaltered and the eof flag will be set, thus the resulting stream will return true for eof(). To iterate through all objects in the bank, 'while ( bankstream >> obj )' will suffice since the stream returned from the fetch will be cast to a bool reflecting the success/failure of the operation.

Precondition:
The bank is open for reading
obj is compatible with the banktype
The eof flag is not set

Exceptions:

ArgumentException_t

IOException_t

Returns:
The modified BankStream
Definition at line 71 of file BankStream_AMOS.cc.
References AMOS_THROW_ARGUMENT, AMOS_THROW_IO, AMOS::B_READ, curr_bid_m, eof(), eof_m, AMOS::IBankable_t::getNCode(), AMOS::ID_t, ignore(), inrange(), AMOS::Bank_t::localizeBID(), AMOS::NULL_ID, AMOS::readLE(), seekg(), AMOS::Size_t, tellg(), and triples_m.

BankStream_t& AMOS::BankStream_t::seekg ( ID_t pos ) [inline]

Seeks to a different position in the BankStream.
This function is constant time. Seeking past the end of stream will set the eof flag. The get pointer is the bank index (BID) of the next object to be fetched.

Precondition:
The bank is open for reading

Parameters:

pos The stream position to seek to (1 based bank index)

Exceptions:

IOException_t

Returns:
The updated BankStream
Definition at line 282 of file BankStream_AMOS.hh.
References AMOS_THROW_IO, AMOS::B_READ, curr_bid_m, eof_m, AMOS::ID_t, and inrange().

BankStream_t& AMOS::BankStream_t::seekg ( bankstreamoff off,

bankseekdir dir

) [inline]

Seeks to a different position in the BankStream.
Seek to a position + offest. bankseekdir's are defined as BEGIN,CURR,END. Where BEGIN is the start of the stream, CURR is the current position in the stream and END is one past the last record in the stream. Only slightly more efficient than fetching the same number of records. Seeking past the end of stream will set the eof flag.

Precondition:
The bank is open for reading

Parameters:

off Number of records to offset from dir

dir The position from which to begin offest

Exceptions:

IOException_t

Returns:
The updated BankStream
Definition at line 257 of file BankStream_AMOS.hh.
References AMOS_THROW_IO, AMOS::B_READ, BEGIN, curr_bid_m, END, and ignore().
Referenced by ignore(), and operator>>().

void AMOS::BankStream_t::setStatus ( signed char status ) [inline]

Set the bank status.
Currently the status is set by the user and not written to the bank. Status is set to zero on object initialization and then left untouched.

Returns:
void

Reimplemented from AMOS::Bank_t.
Definition at line 294 of file BankStream_AMOS.hh.
References AMOS::Bank_t::setStatus().

ID_t AMOS::BankStream_t::tellg ( ) [inline]

Return the current position of the get pointer.
Returns the current position of the get pointer. The get pointer is the bank index (BID) of the next object to be fetched. Note that the difference between two stream positions does NOT tell you how many objects are in between because some of them may be deleted.

Returns:
The current position of the get pointer
Definition at line 307 of file BankStream_AMOS.hh.
References curr_bid_m, and AMOS::ID_t.
Referenced by ignore(), and operator>>().

ID_t AMOS::BankStream_t::tellp ( ) [inline]

Return the current position of the put pointer.
Returns the current position of the put pointer. The put pointer is the bank index (BID) of the next object to be appended. Note that the difference between two stream positions does NOT tell you how many objects are in between because some of them may be deleted.

Returns:
The current position of the put pointer
Definition at line 323 of file BankStream_AMOS.hh.
References AMOS::ID_t.
Referenced by operator<<().

Member Data Documentation

ID_t AMOS::BankStream_t::curr_bid_m [protected]

BID to be returned on next get.
Definition at line 63 of file BankStream_AMOS.hh.
Referenced by ignore(), init(), inrange(), operator>>(), seekg(), and tellg().

const Size_t BankStream_t::DEFAULT_BUFFER_SIZE = 1024 [static, protected]

IO buffer size.

Reimplemented from AMOS::Bank_t.
Definition at line 18 of file BankStream_AMOS.cc.
Referenced by BankStream_t().

bool AMOS::BankStream_t::eof_m [protected]

eof error flag
Definition at line 62 of file BankStream_AMOS.hh.
Referenced by eof(), ignore(), init(), operator>>(), and seekg().

const Size_t BankStream_t::MAX_OPEN_PARTITIONS = 2 [static, protected]

Allowable simultaneously open partitions (one for >>, one for <<).

Reimplemented from AMOS::Bank_t.
Definition at line 19 of file BankStream_AMOS.cc.
Referenced by BankStream_t().

std::vector<const IDMap_t::HashTriple_t *> AMOS::BankStream_t::triples_m [protected]

BID,EID,IID map.
Definition at line 64 of file BankStream_AMOS.hh.
Referenced by BankStream_t(), init(), open(), operator<<(), and operator>>().

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

Generated on Tue May 17 15:19:42 2005 for libAMOS by

1.3.8

AMOS::BankStream_t Class Reference

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation