SourcePro® API Reference Guide

 
List of all members | Public Member Functions | Friends
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
 
RWDBSchemacheckConstraint (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
 
RWDBSchemaforeignKey (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
 
RWDBSchemaoperator= (const RWDBSchema &schema)
 
bool operator== (const RWDBSchema &schema) const
 
RWDBColumn operator[] (size_t index) const
 
RWDBColumn operator[] (const RWCString &name) const
 
RWDBSchemaprimaryKey (const RWDBPrimaryKey &pk)
 
RWDBPrimaryKey primaryKey () const
 
void release () const
 
void setErrorHandler (RWDBStatus::ErrorHandler handler)
 
RWDBStatus status () const
 
RWDBSchemauniqueConstraint (const RWDBUniqueConstraint &uc)
 
RWCString uniqueConstraintsAsString (const RWDBPhraseBook &pb) const
 
RWCString uniqueConstraintsAsString () const
 

Friends

RWvostreamoperator<< (RWvostream &v, const RWDBSchema &obj)
 
RWFileoperator<< (RWFile &f, const RWDBSchema &obj)
 
RWvistreamoperator>> (RWvistream &v, RWDBSchema &obj)
 
RWFileoperator>> (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>
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
nameRepresents the name of the new column appended to the schema.
typeShould be one of the data type attributes of the DB Interface Module. See RWDBValue::ValueType for more explanation.
storageLengthShould be set if the data type requires a size, such as String or Blob data types.
nativeTypeShould 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.
precisionprecision is set when specifying a numeric data type, such as Decimal. The precision of the resulting column is set accordingly.
scalescale is set when specifying a numeric data type, such as Decimal. The scale of the resulting column is set accordingly.
nullAllowedShould 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.
paramTypeShould 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:

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.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.