Schema class. More...

#include <ilviews/dataccess/schema.h>

Inheritance diagram for IliSchema:

Public Member Functions
	IliSchema (IlvDisplay *display)
	This constructor initializes a schema object. More...

	IliSchema (const IliSchema &)
	This is the copy constructor of the `IliSchema` class.

	IliSchema (IlvDisplay *display, IL_STDPREF istream &input)
	This constructor initializes a schema by reading its definition from an input stream. More...

void	addHook (IliTableHook *hook)
	Adds a hook to the list of hooks of the schema object. More...

virtual IlBoolean	allowColumnMove () const
	Returns `IlTrue` if columns can be moved to this schema. More...

IlInt	appendColumn (const char name, const IliDatatype type, IlInt maxlen=-1)
	Appends a new column to the schema. More...

const IliDatatype *	asDatatype () const
	Returns the data type that is defined by this schema. More...

virtual IlBoolean	deleteColumn (IlInt colno)
	Deletes a column. More...

void	endOfBatch ()
	Used in conjunction with the `startOfBatch()` member function to terminate a series of modifications on the schema. More...

IlvAlignment	getColumnAlignment (IlInt colno) const
	Returns the column alignment. More...

const char *	getColumnDefault (IlInt colno) const
	Returns the default value for one column. More...

IlInt	getColumnDisplayWidth (IlInt colno) const
	Returns the display width, in pixels, of one column. More...

const IliFormat &	getColumnFormat (IlInt colno) const
	Returns the format of one column. More...

IlInt	getColumnIndex (const char *name) const
	Returns the position of the column. More...

IlInt	getColumnIndex (IlInt token) const
	Returns the position of the column. More...

const char *	getColumnLabel (IlInt colno) const
	Returns the label of one column. More...

const IliInputMask &	getColumnMask (IlInt colno) const
	Returns the input mask of one column. More...

IlInt	getColumnMaxLength (IlInt colno) const
	Returns the maximum length allowed for one column. More...

const char *	getColumnName (IlInt colno) const
	Returns the name of the column. More...

IlInt	getColumnsCount () const
	Returns the number of columns in the schema. More...

const char *	getColumnTitle (IlInt colno) const
	Returns the title of one column. More...

IlInt	getColumnToken (IlInt colno) const
	Returns the token of the column. More...

const IliDatatype *	getColumnType (IlInt colno) const
	Returns the type of the column. More...

IlvDisplay *	getDisplay () const
	Returns the display of the schema object. More...

const char *	getElementTypeName () const
	Returns the type name of the objects in the collection. More...

const IliSchema *	getNestedSchema (const IliAttributePath &path) const
	Returns the nested schema. More...

IliSchema *	getNestedSchema (const IliAttributePath &path)
	Returns the nested schema. More...

const char *	getSchemaName () const
	Returns the schema name. More...

IlBoolean	hasHook (IliTableHook *hook) const
	Returns `IlTrue` if the hook is already into the list of hooks of the schema object. More...

virtual IlBoolean	insertColumn (IlInt colno, const char colname, const IliDatatype type, IlInt maxlen=-1)
	Inserts a new column in the schema. More...

IlBoolean	isACollection () const
	Returns `IlTrue` if the schema defines a type that is a collection of objects or values. More...

IlBoolean	isASimpleCollection () const
	Returns `IlTrue` if the schema is defined as a simple collection type. More...

IlBoolean	isColumnNullable (IlInt colno) const
	Returns `IlTrue` if the column allows null values. More...

IlBoolean	isColumnPartOfKey (IlInt colno) const
	Returns `IlTrue` if the column is part of the primary key of the schema. More...

IlBoolean	isColumnReadOnly (IlInt colno) const
	Returns `IlTrue` if the column is read-only. More...

IlBoolean	isColumnVisible (IlInt colno) const
	Returns `IlTrue` if the column should be visible. More...

IlBoolean	isPrimaryKeyDefined () const
	Returns `IlTrue` if the schema has one or more columns defined as being part of the primary key. More...

virtual IlBoolean	moveColumn (IlInt from, IlInt to)
	Moves a column. More...

void	removeHook (IliTableHook *hook)
	Removes a hook from the list of hooks of the schema object. More...

void	setAsCollection (IlBoolean flag)
	Sets the schema as a collection type. More...

void	setAsSimpleCollection (IlBoolean flag)
	Sets the schema as a simple collection type. More...

virtual void	setColumnAlignment (IlInt colno, IlvAlignment align)
	Sets the alignment of one column. More...

virtual void	setColumnDefault (IlInt colno, const char *val)
	Sets the default value for one column. More...

virtual void	setColumnDisplayWidth (IlInt colno, IlInt width)
	Sets the display width of one column. More...

virtual void	setColumnFormat (IlInt colno, const IliFormat &fmt)
	Sets the format of the column. More...

virtual void	setColumnLabel (IlInt colno, const char *label)
	Sets the label of one column. More...

virtual void	setColumnMask (IlInt colno, const IliInputMask &mask)
	Sets the input mask of one column. More...

virtual void	setColumnMaxLength (IlInt colno, IlInt maxlen)
	Sets the maximum length for one column. More...

virtual void	setColumnName (IlInt colno, const char *colname)
	Sets the name of the column. More...

virtual void	setColumnNullable (IlInt colno, IlBoolean nullable)
	Determines if the column positioned at colno is nullable (that is, may contain null values). More...

virtual void	setColumnPartOfKey (IlInt colno, IlBoolean partOfKey)
	Specifies whether the column is part of the primary key. More...

virtual void	setColumnReadOnly (IlInt colno, IlBoolean readOnly)
	Specifies whether a column is read-only. More...

virtual void	setColumnTitle (IlInt colno, const char *title)
	Sets the title of one column. More...

virtual void	setColumnType (IlInt colno, const IliDatatype *type)
	Sets the type of the column. More...

virtual void	setColumnVisible (IlInt colno, IlBoolean visible)
	Sets the column visibility. More...

void	setElementTypeName (const char *name)
	Sets the element type name. More...

void	setSchemaName (const char *name)
	Sets the schema name. More...

void	startOfBatch ()
	Used to start a series of modifications on the schema object. More...

virtual void	write (IL_STDPREF ostream &output) const
	Writes the definition of a schema to an output stream in a form suitable to be read back by the stream-based constructor. More...

Public Member Functions inherited from IliRefCounted
IlInt	getRefCount () const
	Returns the reference count of the object. Initially, this property is set to `0`. More...

void	lock () const
	Increments the reference count of the object.

void	unLock () const
	Decrements the reference count of the object. More...

Additional Inherited Members
Protected Member Functions inherited from IliRefCounted
virtual	~IliRefCounted ()
	This is the virtual destructor of the `IliRefCounted` class. More...

Detailed Description

Schema class.

Library: dataccess

The IliSchema class defines an object that has an ordered collection of columns. Each column has a name, a data type and some other attributes. This class serves as a base class for the IliTable class. The IliTable class defines a table object that manages a set of rows with the same schema.

See also: IliDatatype, IliFormat, IliTableHook.

Accessors

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class defines the following accessors:

Data accessors

Name	Type	Equivalent methods
`columnsCount`	Int	`getColumnsCount()`

Method accessors

Name	Return type	Equivalent methods
`getColumn(String colName)`	Object	`Columns[getColumnIndex(colName)]`. See [getColumn] below.
`getColumnAt(Int col)`	Object	`Columns[col]`. See [getColumn] below.

[getColumn] The columns become properties of the schema so that the following are equivalent:

schema.getColumn("NAME")

schema.NAME

Note that if this schema object is part of a more specialized class (such as IliMemoryTable or IliSQLTable), it returns an object whose class is a subclass of IliColumn (such as IliTableColumn or IliSQLTableColumn). This is also the case with the getColumnAt() method.

Constructor & Destructor Documentation

IliSchema::IliSchema ( IlvDisplay * display )

This constructor initializes a schema object.

Initially, the schema definition is empty.

Parameters

display The display.

IliSchema::IliSchema	(	IlvDisplay *	display,
		IL_STDPREF istream &	input
	)

This constructor initializes a schema by reading its definition from an input stream.

Parameters

display	The display.
input	The input stream.

Member Function Documentation

void IliSchema::addHook ( IliTableHook * hook )

Adds a hook to the list of hooks of the schema object.

Note that the ownership of the hook object is not transferred to the schema object (that is, when a schema object is deleted, it does not delete the hooks added to it.)

Parameters

hook The hook.

virtual IlBoolean IliSchema::allowColumnMove ( ) const

virtual

Returns IlTrue if columns can be moved to this schema.

The reason why columns can or cannot be moved depends on the specific subclass of IliSchema that is used.

Returns: IlTrue if columns can be moved to this schema, and IlFalse otherwise.

Reimplemented in IliSQLTable, and IliMemoryTable.

IlInt IliSchema::appendColumn	(	const char *	name,
		const IliDatatype *	type,
		IlInt	maxlen = `-1`
	)

Appends a new column to the schema.

Parameters

name	The column name.
type	The column type.
maxlen	The column maximum length.

Returns: The position of the newly created column.

const IliDatatype* IliSchema::asDatatype ( ) const

Returns the data type that is defined by this schema.

Note that the schema must be completely defined before this member function is called.

Returns: The data type that is defined by this schema.

virtual IlBoolean IliSchema::deleteColumn ( IlInt colno )

virtual

Deletes a column.

Parameters

colno The column position.

Returns: IlTrue if successful and IlFalse if the column position is out of bounds.

void IliSchema::endOfBatch ( )

Used in conjunction with the startOfBatch() member function to terminate a series of modifications on the schema.

Calls to startOfBatch() and endOfBatch() can be nested.

IlvAlignment IliSchema::getColumnAlignment ( IlInt colno ) const

Returns the column alignment.

The default depends on the type of the column.

Parameters

colno The column position.

Returns: The alignment. The return value may be one of the following: IlvLeft, IlvCenter, or IlvRight.

const char* IliSchema::getColumnDefault ( IlInt colno ) const

Returns the default value for one column.

This is the initial value that is assigned to any gadget connected to this column when the end-user inserts a new row into a conforming table. This value is not the same as the SQL default value that the database uses for an unspecified column, during an insert. The default for this property is the empty character string.

Parameters

colno The column position.

Returns: The default value.

IlInt IliSchema::getColumnDisplayWidth ( IlInt colno ) const

Returns the display width, in pixels, of one column.

The default for this property is -1.

Parameters

colno The column position.

Returns: The display width, in pixels. A return value of -1 means that the display width is unspecified.

const IliFormat& IliSchema::getColumnFormat ( IlInt colno ) const

Returns the format of one column.

The default for this property is the default format.

Parameters

colno The column position.

Returns: The format.

IlInt IliSchema::getColumnIndex ( const char * name ) const

Returns the position of the column.

Parameters

name	The column name.

Returns: The position or -1 if no such column is found.

IlInt IliSchema::getColumnIndex ( IlInt token ) const

Returns the position of the column.

Column tokens are automatically assigned to columns at creation time and they do not subsequently change (as opposed to the position of a column, which may change without warning when other columns are inserted or removed).

Parameters

token The column token.

Returns: The position of the column. Otherwise returns -1 if no such column is found.

const char* IliSchema::getColumnLabel ( IlInt colno ) const

Returns the label of one column.

The label of a column is used as a caption for any IliDbField gadgets that are connected to that column. If this property is empty, the column name will be used as a caption. The default for this property is the empty character string.

Parameters

colno The column position.

Returns: The label.

const IliInputMask& IliSchema::getColumnMask ( IlInt colno ) const

Returns the input mask of one column.

The default for this property is the default input mask.

Parameters

colno The column position.

Returns: The input mask.

IlInt IliSchema::getColumnMaxLength ( IlInt colno ) const

Returns the maximum length allowed for one column.

The precise meaning depends on the column type. For example, when the type is IliStringType, this property restricts the type further, by specifying an upper limit on the length of the character strings. A value of -1 specifies that the length is unlimited. The default is -1.

Parameters

colno The column position.

Returns: The maximum length allowed for the column.

const char* IliSchema::getColumnName ( IlInt colno ) const

Returns the name of the column.

Parameters

colno The column position.

Returns: The name or 0 if the position is out of bounds.

IlInt IliSchema::getColumnsCount ( ) const

Returns the number of columns in the schema.

Returns: The count.

const char* IliSchema::getColumnTitle ( IlInt colno ) const

Returns the title of one column.

The title of a column is used as a header in any table gadget connected to that table. If this property is empty, the table gadget will use the name of the column as a header. The default for this property is the empty character string.

Parameters

colno The column position.

Returns: The title.

IlInt IliSchema::getColumnToken ( IlInt colno ) const

Returns the token of the column.

Tokens are automatically assigned to columns at creation time.

Parameters

colno The column position.

Returns: The token of the column or -1 if no such column exists.

const IliDatatype* IliSchema::getColumnType ( IlInt colno ) const

Returns the type of the column.

The default is IliNullType.

Parameters

colno The column position.

Returns: The type or 0 if the position is out of bounds.

IlvDisplay* IliSchema::getDisplay ( ) const

Returns the display of the schema object.

Returns: The display.

const char* IliSchema::getElementTypeName ( ) const

Returns the type name of the objects in the collection.

Returns: The type name if the schema defines a type that is a collection of objects. Otherwise, an empty string is returned.

const IliSchema* IliSchema::getNestedSchema ( const IliAttributePath & path ) const

Returns the nested schema.

Parameters

path	The path of the nested schema.

Returns: The nested schema obtained by following the path or 0 if no such schema exists.

IliSchema* IliSchema::getNestedSchema ( const IliAttributePath & path )

Returns the nested schema.

Parameters

path	The path of the nested schema.

Returns: The nested schema obtained by following the path or 0 if no such schema exists.

const char* IliSchema::getSchemaName ( ) const

Returns the schema name.

When the schema defines a type that is a collection of objects, this property corresponds to the type name of the collection whereas the element type name (as returned by member function getElementTypeName()) corresponds to the type of the elements in the collection.

Returns: The schema name.

IlBoolean IliSchema::hasHook ( IliTableHook * hook ) const

Returns IlTrue if the hook is already into the list of hooks of the schema object.

Parameters

hook The hook.

Returns: IlTrue if the hook is already into the list of hooks of the schema object, otherwise returns IlFalse.

virtual IlBoolean IliSchema::insertColumn	(	IlInt	colno,
		const char *	colname,
		const IliDatatype *	type,
		IlInt	maxlen = `-1`
	)

virtual

Inserts a new column in the schema.

Parameters

colno	The insertion position.
colname	The column name.
type	The column type.
maxlen	The column maximum length. Returns `IlTrue` if the insertion is successful.

IlBoolean IliSchema::isACollection ( ) const

Returns IlTrue if the schema defines a type that is a collection of objects or values.

Returns: IlTrue if the schema defines a type that is a collection of objects or values. Otherwise, IlFalse is returned.

IlBoolean IliSchema::isASimpleCollection ( ) const

Returns IlTrue if the schema is defined as a simple collection type.

The value returned by this member function is meaningful only if the isACollection() member function returns IlTrue. This member function returns IlTrue if the schema is a collection of values instead of a collection of objects. In this case, the schema must have exactly one column. If the schema is not a simple collection, it is a collection of objects and the number of columns is not constrained (except that there must be at least one column.)

Returns: IlTrue if the schema is defined as a simple collection type.

IlBoolean IliSchema::isColumnNullable ( IlInt colno ) const

Returns IlTrue if the column allows null values.

The default is IlTrue.

Parameters

colno The column position.

Returns: IlTrue if the column allows null values.

IlBoolean IliSchema::isColumnPartOfKey ( IlInt colno ) const

Returns IlTrue if the column is part of the primary key of the schema.

primary key is a (minimal) set of columns that uniquely identifies a row, in any table that intends to conform to the schema. In other words, in any conforming table there should never be two distinct rows with the same values over the columns of the primary key. Note that it is sometimes possible to define different candidate keys for a schema. In that case, one of these candidate keys should be selected to serve as the primary key. The default for this property is IlFalse.

Parameters

colno The column position.

Returns: IlTrue if the column is part of the primary key of the schema.

IlBoolean IliSchema::isColumnReadOnly ( IlInt colno ) const

Returns IlTrue if the column is read-only.

The default for this property is IlFalse.

Parameters

colno The column position.

Returns: IlTrue if the column positioned at colno is read-only.

IlBoolean IliSchema::isColumnVisible ( IlInt colno ) const

Returns IlTrue if the column should be visible.

Note that for a column, being invisible is not quite the same as having a display width of zero, since an end-user may resize a visible column at will. The default is IlTrue.

Parameters

colno The column position.

Returns: IlTrue if the column should be visible.

IlBoolean IliSchema::isPrimaryKeyDefined ( ) const

Returns IlTrue if the schema has one or more columns defined as being part of the primary key.

Returns: IlTrue if the schema has one or more columns defined as being part of the primary key.

virtual IlBoolean IliSchema::moveColumn	(	IlInt	from,
		IlInt	to
	)

virtual

Moves a column.

Parameters

from	The start position.
to	The destination position.

Returns: IlTrue if successful.

void IliSchema::removeHook ( IliTableHook * hook )

Removes a hook from the list of hooks of the schema object.

Parameters

hook The hook.

void IliSchema::setAsCollection ( IlBoolean flag )

Sets the schema as a collection type.

Parameters

flag	If `IlTrue`, this member function defines the schema as a collection type.

void IliSchema::setAsSimpleCollection ( IlBoolean flag )

Sets the schema as a simple collection type.

Parameters

flag	If `IlTrue`, it defines the schema as a simple collection type.

virtual void IliSchema::setColumnAlignment	(	IlInt	colno,
		IlvAlignment	align
	)

virtual

Sets the alignment of one column.

Parameters

colno	The column position.
align	The alignment.

virtual void IliSchema::setColumnDefault	(	IlInt	colno,
		const char *	val
	)

virtual

Sets the default value for one column.

Parameters

colno	The column position.
val	The default value. It is copied by this member function.

virtual void IliSchema::setColumnDisplayWidth	(	IlInt	colno,
		IlInt	width
	)

virtual

Sets the display width of one column.

Parameters

colno	The column position.
width	The width in pixels.

virtual void IliSchema::setColumnFormat	(	IlInt	colno,
		const IliFormat &	fmt
	)

virtual

Sets the format of the column.

Parameters

colno	The column position.
fmt	The format.

virtual void IliSchema::setColumnLabel	(	IlInt	colno,
		const char *	label
	)

virtual

Sets the label of one column.

Parameters

colno	The column position.
label	The column label, it is copied by this member function.

virtual void IliSchema::setColumnMask	(	IlInt	colno,
		const IliInputMask &	mask
	)

virtual

Sets the input mask of one column.

Parameters

colno	The column position.
mask	The mask.

virtual void IliSchema::setColumnMaxLength	(	IlInt	colno,
		IlInt	maxlen
	)

virtual

Sets the maximum length for one column.

Parameters

colno	The column position.
maxlen	The maximum length.

Reimplemented in IliMemoryTable.

virtual void IliSchema::setColumnName	(	IlInt	colno,
		const char *	colname
	)

virtual

Sets the name of the column.

Parameters

colno	The column position.
colname	The column name, it is copied by this member function.

virtual void IliSchema::setColumnNullable	(	IlInt	colno,
		IlBoolean	nullable
	)

virtual

Determines if the column positioned at colno is nullable (that is, may contain null values).

Parameters

colno	The column position.
nullable	If `IlTrue`, the column is nullable.

Reimplemented in IliMemoryTable.

virtual void IliSchema::setColumnPartOfKey	(	IlInt	colno,
		IlBoolean	partOfKey
	)

virtual

Specifies whether the column is part of the primary key.

Parameters

colno	The column position.
partOfKey	If `IlTrue`, the column is part of key.

virtual void IliSchema::setColumnReadOnly	(	IlInt	colno,
		IlBoolean	readOnly
	)

virtual

Specifies whether a column is read-only.

Parameters

colno	The column position.
readOnly	If `IlTrue`, the column is read-only.

virtual void IliSchema::setColumnTitle	(	IlInt	colno,
		const char *	title
	)

virtual

Sets the title of one column.

Parameters

colno	The column position.
title	The column title, it is copied by this member function.

virtual void IliSchema::setColumnType	(	IlInt	colno,
		const IliDatatype *	type
	)

virtual

Sets the type of the column.

Parameters

colno	The column position.
type	The column type.

Reimplemented in IliMemoryTable.

virtual void IliSchema::setColumnVisible	(	IlInt	colno,
		IlBoolean	visible
	)

virtual

Sets the column visibility.

Parameters

colno	The column position.
visible	The column visibility. If `IlTrue`, the column is visible.

void IliSchema::setElementTypeName ( const char * name )

Sets the element type name.

Parameters

name	The type name.

void IliSchema::setSchemaName ( const char * name )

Sets the schema name.

Parameters

name The name.

void IliSchema::startOfBatch ( )

Used to start a series of modifications on the schema object.

It allows any connected gadgets to optimize the way they reformat themselves.

virtual void IliSchema::write ( IL_STDPREF ostream & output ) const

virtual

Writes the definition of a schema to an output stream in a form suitable to be read back by the stream-based constructor.

Parameters

output The output stream.

Reimplemented in IliTable, IliSQLTableDef, IliMemoryTable, IliMapTable, and IliStringsTable.

Public Member Functions

Additional Inherited Members

Detailed Description

Accessors

Data accessors

Method accessors

Constructor & Destructor Documentation

Member Function Documentation