RWDBSchema Class Reference

An ordered collection of RWDBColumn instances, encapsulating the database notion of a schema. More...

#include <rw/db/schema.h>

Public Member Functions
	RWDBSchema ()
	RWDBSchema (const RWDBSchema &schema)
	RWDBSchema (const RWDBPrimaryKey &pk)
void	acquire () const
RWDBColumn	appendColumn (const RWCString &name, RWDBValue::ValueType type=RWDBValue::NoType, long storageLength=RWDB_NO_TRAIT, int nativeType=RWDB_NO_TRAIT, int precision=RWDB_NO_TRAIT, int scale=RWDB_NO_TRAIT, bool nullAllowed=true, RWDBColumn::ParamType paramType=RWDBColumn::notAParameter)
RWDBColumn	appendColumn (const RWDBColumn &col)
RWCString	asString () const
RWCString	asString (const RWDBPhraseBook &phrasebook) const
RWspace	binaryStoreSize () const
RWDBSchema &	checkConstraint (const RWDBCheckConstraint &cc)
RWCString	checkConstraintsAsString (const RWDBPhraseBook &pb) const
RWCString	checkConstraintsAsString () const
RWDBSchema	clone () const
RWDBColumn	column (size_t index) const
RWDBColumn	column (const RWCString &name) const
RWDBColumn	column (const RWCString &name, RWCString::caseCompare caseCompare) const
RWCString	columnName (size_t index) const
size_t	entries () const
RWDBStatus::ErrorHandler	errorHandler () const
RWDBSchema &	foreignKey (const RWDBForeignKey &fk)
size_t	index (const RWCString &name) const
size_t	index (const RWCString &name, RWCString::caseCompare caseCompare) const
size_t	index (const RWDBColumn &column) const
bool	isEmpty () const
bool	isValid () const
RWCString	keysAsString (const RWDBPhraseBook &pb) const
RWCString	keysAsString () const
bool	operator!= (const RWDBSchema &schema) const
RWDBSchema &	operator= (const RWDBSchema &schema)
bool	operator== (const RWDBSchema &schema) const
RWDBColumn	operator[] (size_t index) const
RWDBColumn	operator[] (const RWCString &name) const
RWDBSchema &	primaryKey (const RWDBPrimaryKey &pk)
RWDBPrimaryKey	primaryKey () const
void	release () const
void	setErrorHandler (RWDBStatus::ErrorHandler handler)
RWDBStatus	status () const
RWDBSchema &	uniqueConstraint (const RWDBUniqueConstraint &uc)
RWCString	uniqueConstraintsAsString (const RWDBPhraseBook &pb) const
RWCString	uniqueConstraintsAsString () const

Friends
RWvostream &	operator<< (RWvostream &v, const RWDBSchema &obj)
RWFile &	operator<< (RWFile &f, const RWDBSchema &obj)
RWvistream &	operator>> (RWvistream &v, RWDBSchema &obj)
RWFile &	operator>> (RWFile &f, RWDBSchema &obj)

Detailed Description

Class RWDBSchema is an ordered collection of RWDBColumn instances. An RWDBSchema serves as an encapsulation of the database notion of schema, a set of attributes defining a table. The DB Interface Module extends this notion slightly by using an RWDBSchema to define a stored procedure's formal parameter list, and to specify a list of columns wherever one is required. Each RWDBSchema can have foreign key, primary key, check constraint, and unique constraint information associated with it.

Every RWDBTable has an RWDBSchema. An application can interrogate the RWDBSchema of an RWDBTable for schema information, or obtain a copy of an RWDBSchema for its own use. An RWDBSchema instance may be used to create a database table. To do this, an application can use an RWDBSchema obtained from an existing RWDBTable, modify an existing RWDBSchema, or build one from scratch using the methods appendColumn(), foreignKey(), primaryKey(), checkConstraint(), and uniqueConstraint().

This class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators reference the old object and, as a result, are very fast. An actual copy is made only when the object is about to be changed. The net result is excellent performance, with easy-to-understand copy semantics.

Synopsis

#include <rw/db/schema.h>

RWDBSchema s;
s = myTable.schema();

Constructor & Destructor Documentation

RWDBSchema::RWDBSchema

(

)

The default constructor creates an empty RWDBSchema, that is, one with zero columns.

RWDBSchema::RWDBSchema

(

const RWDBSchema &

schema

)

Copy constructor. Self shares an implementation with schema until the data is modified.

RWDBSchema::RWDBSchema

(

const RWDBPrimaryKey &

pk

)

Constructor. Self shares an implementation with pk until the data is modified.

Member Function Documentation

void RWDBSchema::acquire

(

)

const

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object.

Note

In single-threaded builds, this function evaluates to a no-op.

RWDBColumn RWDBSchema::appendColumn	(	const RWCString &	name,
		RWDBValue::ValueType	type = RWDBValue::NoType,
		long	storageLength = RWDB_NO_TRAIT,
		int	nativeType = RWDB_NO_TRAIT,
		int	precision = RWDB_NO_TRAIT,
		int	scale = RWDB_NO_TRAIT,
		bool	nullAllowed = true,
		RWDBColumn::ParamType	paramType = RWDBColumn::notAParameter
	)

Constructs a new RWDBColumn according to the supplied parameters, appends it to self, and returns it. Applications using this method must usually supply only name and type, as well as storageLength, if type is RWDBValue::String.

Parameters

name	Represents the name of the new column appended to the schema.
type	Should be one of the data type attributes of the DB Interface Module. See RWDBValue::ValueType for more explanation.
storageLength	Should be set if the data type requires a size, such as String or Blob data types.
nativeType	Should be set if one of the data type attributes of the DB Interface Module cannot represent the native data type of the database. If this field is set, type should be left as the default to show that a native data type was requested. You can determine native data types of a specific database through documentation or header files.
precision	precision is set when specifying a numeric data type, such as Decimal. The precision of the resulting column is set accordingly.
scale	scale is set when specifying a numeric data type, such as Decimal. The scale of the resulting column is set accordingly.
nullAllowed	Should be set to false if a column requires a value. The default value of true allows a column's value to be set to NULL.
paramType	Should be set when specifying the parameters of a stored procedure. See RWDBStoredProc for more information on how to use this parameter. For normal tables, use the default value.

RWDBColumn RWDBSchema::appendColumn

(

const RWDBColumn &

col

)

Creates a deep copy of the RWDBColumn col, using the RWDBColumn::clone() method. Appends the copied column to self, and returns it.

RWCString RWDBSchema::asString

(

)

const

Produces a comma-delimited list of names of RWDBColumn instances in self.

RWCString RWDBSchema::asString

(

const RWDBPhraseBook &

phrasebook

)

const

Produces a list of the names of the RWDBColumn instances in self, delimited by the listDelimiter character defined in phrasebook.

RWspace RWDBSchema::binaryStoreSize

(

)

const

Returns the number of bytes necessary to store the object using the global functions:

RWFile& operator<<(RWFile&, const RWDBSchema&);
RWvostream& operator<<(RWvostream&, const RWDBSchema&);

RWDBSchema& RWDBSchema::checkConstraint

(

const RWDBCheckConstraint &

cc

)

Appends a deep copy of cc to self's list of check constraints. Returns a reference to self.

RWCString RWDBSchema::checkConstraintsAsString

(

const RWDBPhraseBook &

pb

)

const

Returns a comma-delimited string of the check constraints attached to self.

RWCString RWDBSchema::checkConstraintsAsString

(

)

const

Returns a comma-delimited string of the check constraints attached to self.

RWDBSchema RWDBSchema::clone

(

)

const

Produces a deep copy of self.

RWDBColumn RWDBSchema::column

(

size_t

index

)

const

Returns a shallow copy of the column from self at the specified index. If index is out of range, returns an RWDBColumn with a status of RWDBStatus::invalidPosition.

RWDBColumn RWDBSchema::column

(

const RWCString &

name

)

const

Returns a shallow copy of the column from self whose name matches the given name. If there is no match, returns an RWDBColumn with a status of RWDBStatus::columnNotFound.

RWDBColumn RWDBSchema::column	(	const RWCString &	name,
		RWCString::caseCompare	caseCompare
	)		const

Returns a shallow copy of the column from self whose name matches the given name, according to caseCompare. If there is no match, returns an RWDBColumn with a status of RWDBStatus::columnNotFound.

RWCString RWDBSchema::columnName

(

size_t

index

)

const

Returns the name of the column at the specified index.

size_t RWDBSchema::entries

(

)

const

Returns the number of RWDBColumn instances in self.

RWDBStatus::ErrorHandler RWDBSchema::errorHandler

(

)

const

Returns the error handler attached to self.

RWDBSchema& RWDBSchema::foreignKey

(

const RWDBForeignKey &

fk

)

Appends a deep copy of fk to self's list of foreign keys. Returns a reference to self.

size_t RWDBSchema::index

(

const RWCString &

name

)

const

Returns the index of the first RWDBColumn in self with the given name. Returns RW_NPOS if no such column is found.

size_t RWDBSchema::index	(	const RWCString &	name,
		RWCString::caseCompare	caseCompare
	)		const

Returns the index of the first column from self whose name matches the given name, according to caseCompare. If there is no match, returns RW_NPOS.

size_t RWDBSchema::index

(

const RWDBColumn &

column

)

const

Returns the index of the first RWDBColumn in self with the same name as the name of the given column. Returns RW_NPOS if no such column is found.

bool RWDBSchema::isEmpty

(

)

const

Returns true if self contains zero entries, otherwise returns false.

bool RWDBSchema::isValid

(

)

const

Returns true if self's status is RWDBStatus::ok, otherwise returns false.

RWCString RWDBSchema::keysAsString

(

const RWDBPhraseBook &

pb

)

const

Returns a comma-delimited string of the foreign keys attached to self.

RWCString RWDBSchema::keysAsString

(

)

const

Returns a comma-delimited string of the foreign keys attached to self.

bool RWDBSchema::operator!=

(

const RWDBSchema &

schema

)

const

Compares self to schema. Returns true if schema and self are unequal.

RWDBSchema& RWDBSchema::operator=

(

const RWDBSchema &

schema

)

Assignment operator. Self shares an implementation with schema until the data is modified.

bool RWDBSchema::operator==

(

const RWDBSchema &

schema

)

const

Compares self to schema. Returns true if schema and self are identical.

RWDBColumn RWDBSchema::operator[]

(

size_t

index

)

const

Returns the RWDBColumn in self at position index. If index is out of range, returns an RWDBColumn with a status of RWDBStatus::invalidPosition. Indexing into an empty schema is treated as out of range.

Note

The returned RWDBColumn is not a deep copy; modifications to it change the containing schema.

RWDBColumn RWDBSchema::operator[]

(

const RWCString &

name

)

const

Returns the first RWDBColumn in self with the given name. If no such column exists, an RWDBColumn is returned with a status RWDBStatus::columnNotFound.

Note

The returned RWDBColumn is not a deep copy; modifications to it change the containing schema.

RWDBSchema& RWDBSchema::primaryKey

(

const RWDBPrimaryKey &

pk

)

Sets self's primary key to pk. Returns a reference to self.

RWDBPrimaryKey RWDBSchema::primaryKey

(

)

const

Returns the primary key associated with self. An empty RWDBPrimaryKey indicates there is no primary key associated with self.

Note

If this schema was retrieved from a database table using RWDBTable::schema(), the primary key will be set only if RWDBTable::primaryKey() was called first.

void RWDBSchema::release

(

)

const

Releases a previously acquired mutex. This function can be called from a const object.

Note

In single-threaded builds, this function evaluates to a no-op.

void RWDBSchema::setErrorHandler

(

RWDBStatus::ErrorHandler

handler

)

Installs handler as self's error handler. The supplied handler is inherited by all objects produced by self. By default, the RWDBStatus::ErrorHandler of an RWDBSchema is inherited from the object that produced it; this method overrides the default.

RWDBStatus RWDBSchema::status

(

)

const

Returns the current status of self.

RWDBSchema& RWDBSchema::uniqueConstraint

(

const RWDBUniqueConstraint &

uc

)

Appends a deep copy of uc to self's list of unique constraints. Returns a reference to self.

RWCString RWDBSchema::uniqueConstraintsAsString

(

const RWDBPhraseBook &

pb

)

const

Returns a comma-delimited string of the unique constraints attached to self.

RWCString RWDBSchema::uniqueConstraintsAsString

(

)

const

Returns a comma-delimited string of the unique constraints attached to self.

Friends And Related Function Documentation

RWvostream& operator<< ( RWvostream &  v, const RWDBSchema &  obj  )

friend

Saves obj to an RWvostream.

Throws an RWExternalErr if the stream is corrupted.

RWFile& operator<< ( RWFile &  f, const RWDBSchema &  obj  )

friend

Saves obj to an RWFile.

Throws an RWExternalErr if the file is corrupted.

RWvistream& operator>> ( RWvistream &  v, RWDBSchema &  obj  )

friend

Restores an RWDBSchema into obj from an RWvistream, replacing the previous contents of obj.

Throws an RWExternalErr if the stream is corrupted.

RWFile& operator>> ( RWFile &  f, RWDBSchema &  obj  )

friend

Restores an RWDBSchema into obj from an RWFile, replacing the previous contents of obj.

Throws an RWExternalErr if the file is corrupted.