Column

Reference documentation for a Column object

Overview

A Column object represents an individual column in Table in a Database Server.

File Structure

The properties for a Column are stored under in the resources directory in a Database Information (.dbi) File.

Properties Summary

The following properties can be configured for a Column object

Property	Summary
Name	The name of the column derived from the original data source
Type	This is the data type of the column
Length	This is the amount of storage allocated to single column for a single record
Row ident	This is a row identifier that uniquely identifies that row (or data record) in a database
Allow Null	This specifies if the value stored in that column can be null or not
Title	The human-readable name for a column
Default Format	The formatting that is used when the column is bound to a field element
Foreign Type	This indicates that a column is a foreign key to another table in the same database
Sorting Ignoring case	This specifies how sorting should be done regarding casing
Sorting Null precedence	This specifies how null values should be sorted
Flag Excluded	This excludes a column from the Servoy runtime environment
Flag UUID	This identifies columns whose values are treated as UUID
Flag Tenant	This identifies columns that are marked as a tenant column
Description	This is a container for additional metadata
Auto Enter	The ways in which a column may be automatically populated when a record is created
Auto Enter : System Value	This specifies which system value should be used to automatically populate a record
Auto Enter : Custom Value	This is a literal value which may be used as a default
Auto Enter : Database Default	This indicates that the value is deferred to the database at the time of insert
Auto Enter : Lookup Value	This provides the option to auto-enter a value that is contextual to the record being inserted
Auto Enter : Sequence	This is used to auto-increment a column's value
Validation Name	This indicates which built-in validation rule should be implemented
Validation Properties	This indicates the values that need to be validated
Conversion Name	This indicates which type of conversion should be implemented
converterProperties .fromObjectMethodName	The global method that converts from UI value to dataprovider value
converterProperties .toObjectMethodName	The global method that converts from dataprovider value to UI value
converterProperties .type	The UI data type (one of TEXT, INTEGER, NUMBER, DATETIME or MEDIA, so the resulting type of the toObjectMethodName method)

Properties Details

The following properties can be configured for a Column object

Name

This is the name or dataProviderID of the column derived from the SQL name in the original data source. The name may be prettified (lowercase and underscore) for database vendors having non-standard column naming.

Type: String Required: true

Type

This is the data type of the column. All data types are generalized to one of six standard types: DATETIME INTEGER MEDIA NUMBER TEXT UUID

Type: Number Required: true

Length

For certain data types, databases must enforce the amount of storage allocated to single column for a single record. Data types which accommodate variable length entries, such as text, decimal numbers and binary data will have a length property. Servoy will infer and display this property in the column definition.

Row ident

Servoy is designed to work with regular database tables as well as SQL Views. Regular database tables will have a primary key, consisting of one or more columns, who's value uniquely identifies a record in the table. Servoy will infer the primary key from the database table. However, in the case of SQL Views, which don't have a built-in primary key, the developer must specify which column(s) can be considered the unique row identifier.

Allow Null

Relational database tables may enforce non-null constraints on certain columns, typically for primary key and other essential columns. Servoy will infer from any such constraints from database table and reflect

Title

The Title property of a column is simply the human-readable name for a column. When a field is placed on a form with the Place with labels option, the label's text property will be initialized to the title property for the column to reach the field is bound. For multilingual applications, it is ideal to populate a column's title property with an i18n message key, thus allowing field labels to default to message key, which is translated at runtime.

Default Format

The Default Format property of a column will enforce the formatting that is used when the column is bound to a field element. The field element's format property will assume the default format of the column unless it is overridden in the element.

Foreign Type

This is a simple metadata property to indicate that a column is a foreign key to another table in the same database. One can set the Foreign Type property to the target table. This provides metadata so developers will know that a column is used as a foreign key. Servoy will use this information when new relations are created between the tables and auto-fill the keys. This property is also used by the mergeRecords method of the databaseManager API to update any affected related records, such that they'll reference a new key.

Sorting Ignoring case

This specifies that sorting should always be done with upper/lower casing or with database default.

Sorting Null precedence

This specifies that the sort order should be with nulls first or last or with database default.

Flag Excluded

Enabling a column's Excluded Flag will completely exclude a column from the Servoy runtime environment. This means that Servoy will exclude this column for every query that it issues. This option is ideal to enforce that certain columns are never available in a Servoy application.

Flag UUID

Servoy supports the use of Universally Unique Identifiers (UUID). A UUID is a 16-byte number which can be (practically) guaranteed to be unique across computing environments, making it ideal to use for sequences in scenarios where traditional numeric sequences are not adequate, for example when syncing data which is generated offline. It is generally not feasible to store UUIDs as numeric data types because the number is so large. Rather UUIDs are most easily stored as 36-character strings. When using a text column to store UUIDs, one should mark the column's UUID flag. Thus, Servoy will provide programmatic access to this column in the form of a built-in UUID data type, which allows both string and byte representation.

Flag Tenant

This identifies columns that are marked as a tenant column.

Description

A column's description property is a simple container for additional metadata, such as programmer notes about the column's purpose, etc.

Auto Enter

Servoy provides several ways in which a column may be automatically populated when a record is created. Some of the auto-enter options are also applicable when an existing record is updated.

System Value

• Database-Managed: Indicates that the value is deferred to the database at the time of insert. The value is populated and controlled by the database and it will not be overwritten from Servoy.

• Creation User UID: The UID parameter that was supplied at the time of login, entered at the time of record creation.
• Modification User UID: The UID parameter that was supplied at the time of login, reentered each time the record is modified.
• Creation Datetime: The current date and time on the client, entered at the time of record creation.

• Creation Server Datetime: The current date and time on the application server, entered at the time of record creation.

• Modification Datetime: The current date and time on the client, reentered each time the record is modified.

• Modification Server Datetime: The current date and time on the application server, reentered each time the record is modified.

Custom Value

A custom value is simply a literal value (i.e. 'Blue', 1.5) which may be used as a default. This option is only available for Integer, Number and Text data types.

Database Default

This indicates that the value is deferred to the database at the time of insert. However, unlike Database-Managed system values, this value can be modified from Servoy after the record is inserted.

Lookup Value

Lookup Values provide the option to auto-enter a value that is contextual to the record being inserted. Options include any of the record's data providers, any data providers from foundsets related to the record, as well as an global relations or variables.

Sequence

Sequences may be used to auto-increment a column's value. This is ideal for populating primary key columns, which must be unique.

• Servoy Sequence: DEPRICATED, this sequence type is already removed from the Table Editor UI for new column, it should not be used anymore. use a database sequence or database identity for plain number columns, or convert to UUID's

• Database Sequence: Servoy will call a named sequence in the database to populate the value. The column will be populated and available prior to inserting the record.

• Database Identity: The sequential values are managed and populated by the database. The column is not populated until after the record is inserted.

• UUID Generation: Servoy will automatically populate a text column with a textual representation of a UUID. Be sure that the column's UUID Flag is also enabled.

Validation

Servoy provides an opportunity to implement validation rules at the column level. There are several built-in validation rules, which may be implemented at design-time. Additionally, custom validation rules may be written in as a JavaScript method which is bound to a column. Servoy also allows the contribution of a column validator by a java plugin.

In Servoy 2020.9 by default the validation will only be called when databaseManager.validate(record) is call or when saveData() is called, which does call validate(record) itself also. This behavior can be set back by a property "servoy.execute.column.validators.only.on.validate_and_save" (which is configurable in the ui in the Colunm validation part of the table editor). If set back or before 2020.9 the behavior is that a validation event occurs at the moment a record's value for a column changes. This may be the result of a user's action or some code which is executed. When validation fails, a Servoy Exception is raised for Invalid Input, which may be trapped in a solution's onError event handler. With 2020.9 it is better to use the new validation system see: Data/Record/Column validation.

Numeric Range Validation

Servoy provides built-in numeric validation for Integer and Number data types. Providing upper and lower bounds will automatically enforce that any value entered is between (inclusive) the range provided. Providing only a lower bound will enforce that any value entered is greater-than-or-equal-to the bound. Providing only an upper bound will enforce that any value entered is less-than-or-equal-to the bound.

Size/Length Validation

Servoy provides built-in validation for the size/length of a value in a column. This rule is applicable to Text and Media data types. Setting the length property for Text columns will enforce that value entered has a length of characters which is less-than-or-equal-to the length specified in the rule. Setting the size property for Media columns will enforce that value entered has a size, measured in number of bytes, which is less-than-or-equal-to the size specified in the rule.

RegEx Validation

Servoy offers the flexible pattern matching capability of Regular Expressions as a means to apply validation rules to Text columns. Providing a RegEx value will enforce that any value entered into the Text column must match on the expression. RegEx is an excellent way to match on patterns, such as phone numbers, email addresses, and much more. RegExLib is a useful site containing user-generated libraries of expressions to suit many needs.

Email Validation

Servoy provides a built-in email validation rule, which enforces that any Text column matches a pattern which is similar to email addresses. This pattern is ideal for most use cases. However, developers may implement their own RegEx validation to ensure an exact match on the pattern of their choice.

Indentifier Validation

A build in validator to make sure that the values are javascript based identifiers (so can be used in scripting or for solution model stuff)

Custom Validation

Apart from the built-in validation rules, Servoy allows developers to author business logic to enforce their own validation rule for a column. A Global Method may be bound to a column, such that when a validation event occurs for the column, the method is invoked. The value that is entered is passed into the method and a developer may then execute any evaluation of the value before returning a boolean value; true indicates that validation is successful.

/**
 * Custom Validation rule: Must be Dog or Cat (case insensitive)
 * @param {Object} obj The value that will be validated
 * @returns {Boolean} True when successful
 * @properties={typeid:24,uuid:"655B9F0E-A1A2-4B0B-84CD-8E299546DB57"}
 */
function validateColumn(obj) {
    return 'Dog'.equalsIgnoreCase(obj) || 'Cat'.equalsIgnoreCase(obj);
}

Column Validator from Java Code (plugin)

A Column validator can be contributed by a java plugin. See Providing converters and validators from plugins for more information.

Conversion

Some scenarios require that a value is stored in a database column in one form and written to and read from the database column in another form. Servoy supports this requirement with a feature called Column Conversion and it has three applications: String Serialization, Blob Serialization and Global Method Conversion.

Servoy also allows the contribution of a column converter by a java plugin.

String Serialization

Servoy supports object persistence using String Serialization, which involves the conversion of a runtime object into a string format, which can then be persisted in a database column. When the column is read from the database, the persistent string will be deserialized back into a runtime object. Because Servoy uses JavaScript as its scripting language, runtime objects will be serialized into standard JSON format.

String Serialization can only be used for column type TEXT.

//  Construct an object to capture some custom settings and write it directly to a Text column called 'custom_settings'
var obj = new Object();
obj.name = 'foobar';
obj.message = 'Hello World'; 
 
// at this point it is serialized into the string: "{name:'foobar',message:'Hello World'}"
custom_settings = obj;
databaseManager.saveData();
 
// ...read object properties at a later time...
application.output(custom_settings.message + 'My name is: ' + custom_settings.name);

Remember that only by assigning an object to a data provider will the serialized string be actually stored. It is not possible to set individual instance properties of an object to directly modify the serialized string.

// For Example
my_data_provider.property = 'Foobar'; // This will have no effect on the data provider
 
// Instead
var obj = my_data_provider; // read the data provider into a runtime object
obj.property = 'Foo Bar';   // Modify the Object's instance properties
my_data_provider = obj;     // And reassign it to the data providerdatabaseManager.saveData();

Blob Serialization

Servoy provides Blob Serialization for persisting an object as a Blob. This involves converting the runtime object into a Blob, which is then persisted in the database column. When retrieving the column data from the database, the Blob is deserialized back into a runtime object.

Blob Serialization can only be used for column type MEDIA.

Global Method Conversion

Servoy allows a database column to be bound to custom business logic, giving developers control over how a value is converted when it is written to, and read from the data provider.

The nomenclature refers to the Object Value, seen in the GUI, as well as used programmatically, and the Database Value, the value stored in the data provider and persisting in the database.

The column is bound to two methods which facilitate the conversion between the Object Value and the Database Value. A developer may also specify an optional Object Data Type, prompting Servoy to provide the data in an alternate data type in lieu of the default column type. This is useful when values are stored in a non-standard storage type to accommodate legacy systems, but should be treated like standard data type in the runtime.

Object to Database Method

This method is called anytime a value is written to the data provider. It will be called regardless of the origin of the action, i.e. GUI event or programmatically. It will be called before data is committed to the database.

Parameters

Object - The value that is being written to the data provider String - The column's data type: TEXT, INTEGER, NUMBER, DATETIME, MEDIA

Returns Object - The converted value that will actually be written to the data provider.

Example

Perhaps the most classic use case is the conversion between SI Units, where a database is standardized on a certain unit, but an application requires that values be written and read in multiple units, often to support different locales / preferences. Imagine a database column for temperature, which is standardized on Celsius, but an application which allows data entry in Celsius, Fahrenheit and Kelvin.

/**
 * This method auto-converts from client units to Celsius as the value is being written to the data provider
 * @parameter {Object} value The value of the runtime object
 * @parameter {String} columnType The data type of the column
 * @returns {Object} The value converted into celsius
 * @properties={typeid:24,uuid:"303ACB93-3B0E-4B9C-9550-D78FF17343C2"}
 */
function objectToDB(value, columnType) {
 
    // evaluate client unit settings
    switch(tempUnits){
 
        // Already in C, just return it as is
        case C :
            return value;
 
        // Fahrenheit,use conversion formula
        case F :
            return (5/9)*(value-32);
 
        // Kelvin,use conversion formula
        case K :
            return value - 273;
    }
}

Database to Object Method

This method is called anytime a value is read from the data provider. It will be called when it is displayed in the GUI or read programmatically.

Parameters Object - The value that is being read from the data provider String - The column's data type: TEXT, INTEGER, NUMBER, DATETIME, MEDIA

Returns Object - The converted value that will actually be displayed in the GUI and read programmatically.

Example

Perhaps the most classic use case is the conversion between SI Units, where a database is standardized on a certain unit, but an application requires that values be written and read in multiple units, often to support different locales / preferences. Imagine a database column for temperature, which is standardized on Celsius, but an application which allows data entry in Celsius, Fahrenheit and Kelvin.

/**
 * This method converts database values (Celsius) into the current client units for degrees
 * @parameter {Object} value The value stored in the column
 * @parameter {String} columnType The data type of the column
 * @returns {Object} The value that was converted into current client units
 * @properties={typeid:24,uuid:"63C4D552-531C-48DB-A6C6-ED02F4603C20"}
 */
function dbToObject(value, columnType) {
 
    //  evaluate client unit settings
    switch(tempUnits){
 
        // Already using C, just return it as is
        case C :
            return value;
 
        // Fahrenheit, use conversion formula
        case F :
            return (9/5) * value + 32;
 
        // Kelvin, use conversion formula
        case K :
            return value + 273;
    }
}

Converted Object Type

One can optionally specify the data type of the Object Value. This is useful in situations where the stored value is a different data type than the object value.

Example

The application talks to a database that is storing dates as 8-character text columns to support legacy applications. By setting the Converted Object Type setting to DATETIME, Servoy will treat the column as a date object. Moreover, the two conversion methods written by the developer should assume the Object Value is a Date object.

/**
 * This method converts Text data stored in the database column, presenting it as Date object
 * @parameter {Object} value The value stored in the column
 * @parameter {String} columnType The data type of the column
 * @returns {Object} The value that was converted
 * @properties={typeid:24,uuid:"16BDC049-E63B-47C4-B49C-595D916FD51B"}
 */
function dbToObj(value, columnType) {
    return utils.dateFormat(value,'MMddyyyy');
}

Column Converter from Java Code (plugin)

A Column converter can be contributed by a java plugin. See Providing Converters and Validators from Plugins for more information.