RWDBSchema Class Reference
[Databases]

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

#include <rw/db/schema.h>

List of all members.

Public Member Functions
	RWDBSchema ()
	RWDBSchema (const RWDBSchema &schema)
RWDBSchema &	operator= (const RWDBSchema &schema)
bool	operator== (const RWDBSchema &schema) const
bool	operator!= (const RWDBSchema &schema) const
RWDBSchema	clone () const
void	acquire () const
void	release () const
RWDBColumn	operator[] (size_t index) const
RWDBColumn	operator[] (const RWCString &name) 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	index (const RWCString &name) const
size_t	index (const RWCString &name, RWCString::caseCompare caseCompare) const
size_t	index (const RWDBColumn &column) const
RWCString	keysAsString (const RWDBPhraseBook &pb)
RWCString	keysAsString ()
size_t	entries () const
bool	isEmpty () const
RWDBSchema &	foreignKey (const RWDBForeignKey &fk)
RWDBSchema &	primaryKey (const RWDBSchema &pk)
RWDBSchema	primaryKey ()
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
void	setErrorHandler (RWDBStatus::ErrorHandler handler)
RWDBStatus::ErrorHandler	errorHandler () const
bool	isValid () const
RWDBStatus	status () const

---

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 and primary key 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(), and primaryKey().

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;
 RWDBSchema 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.

---

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 RWDBColumn &

col

)

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

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
	scale	precision and scale are set when specifying a numeric data type, such as Decimal. The precision and 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.

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.

RWCString RWDBSchema::asString

(

)

const

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

RWDBSchema RWDBSchema::clone

(

)

const

Produces a deep copy of self.

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.

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

(

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.

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 fk to self's list of foreign keys. Returns a reference to self.

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.

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 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.

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

(

)

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

RWCString RWDBSchema::keysAsString

(

const RWDBPhraseBook &

pb

)

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[]

(

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.

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.

RWDBSchema RWDBSchema::primaryKey

(

)

Returns the primary key associated with self as an RWDBSchema. An empty schema 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.

RWDBSchema& RWDBSchema::primaryKey

(

const RWDBSchema &

pk

)

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

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.