Relation

Overview

The Relation class represents a connection between two data sources, typically involving a primary and a foreign table.

It provides functionality for managing the relationship between data providers, including the operators used for linking the two tables. The relation can define how the data should be sorted, whether related records can be created or deleted, and how the related records are handled during find and sort operations.

The class allows for checking if the relation items are valid, creating new relation items, and validating data types and foreign key relationships. * It supports encapsulation levels to control its visibility in scripting and modules, and it can also be deprecated with a description. * A key feature of this class is the ability to specify the join type for the relationship, such as an inner join or a left outer join, * which affects how records are returned during operations.

Additionally, the relation can be configured to handle cascading deletes, creation of related records, and whether the relation spans multiple servers. * It also supports various operations for handling global and literal data providers, and it offers a mechanism for caching data providers for improved performance.

Overall, the `Relation` class provides relationship management between data sources in the Servoy environment, offering fine-grained control over data handling, sorting, and record management.

Properties Summarized

Type	Name	Summary
Boolean	allowCreationRelatedRecords	Flag that tells if related records can be created through this relation, or not.
Boolean	allowParentDeleteWhenHavingRelatedRecords	Flag that tells if the parent record can be deleted while it has related records.
String	comment	Additional information, such as programmer notes about this relation's purpose.
Boolean	deleteRelatedRecords	Flag that tells if related records (from a related foundset) should be deleted or not when a parent record is deleted.
String	deprecated	Gets the deprecation info for this element.
Number	encapsulation	A relation has an encapsulation property, similar to the form encapsulation property.
String	foreignDataSource	Qualified name of the foreign data source.
String	initialSort	Foundsets, including related foundsets, have a sort property.
Number	joinType	The join type that is performed between the primary table and the foreign table.
String	name	The name of the relation.
String	primaryDataSource	Qualified name of the primary data source.

Properties Detailed

allowCreationRelatedRecords

Flag that tells if related records can be created through this relation, or not.

This option is enabled by default, and it specifies that records can be created within a related foundset. Moreover, when records are created in a related foundset, the key columns in the new record may be automatically filled with the corresponding values from the source record.

Example: Assume a relation, _customers_to_orders_ defined by a single key expression, customers.customerid = orders.customerid

customerid;         // 123, the customer's id
customers_to_orders.newRecord();// create the new record
customers_to_orders.customerid; // 123, the order record's foreign key is auto-filled

Key columns will be auto-filled for expressions using the following operators:

• =

• #=

• ^||=

If this option is disabled, then records cannot be created in a related foundset. If attempted, a [ServoyException]() is raised with the error code, [NO_RELATED_CREATE_ACCESS]().

Type Boolean

Sample

"true" or "false"

allowParentDeleteWhenHavingRelatedRecords

Flag that tells if the parent record can be deleted while it has related records. This option is enabled by default.

When disabled, it will prevent the deleting of a record from the source table if the related foundset contains one or more records. If the delete fails, a [ServoyException]() is raised with the error code, [NO_PARENT_DELETE_WITH_RELATED_RECORDS]().

Example: Assume the relation customers_to_orders has this option disabled. An attempt to delete a customer record will fail, if that customer has one or more orders.

Type Boolean

Sample

"true" or "false"

comment

Additional information, such as programmer notes about this relation's purpose.

Type String

Sample

"gets order details table data starting from orders table"

deleteRelatedRecords

Flag that tells if related records (from a related foundset) should be deleted or not when a parent record is deleted. Moreover, it also enforces a cascading delete, such that when a source record is deleted, all records in the related foundset will also be deleted, eliminating the possibility of orphaned records.

Example: Assume the relation customers_to_orders has enabled this option. The deleting of the customer record will cause all of the related order records to be deleted.

The default value of this flag is "false".

Type Boolean

Sample

"true" or "false"

deprecated

Gets the deprecation info for this element.

Type String the deprecation info for this object or null if it is not deprecated

Sample

"not used anymore, replaced with ..."

encapsulation

A relation has an encapsulation property, similar to the form encapsulation property. The following can be used:

• Public – accessible from everywhere

• Hide in Scripting; Module Scope – code completion is disabled for the relation; it is accessible only from the module that it was created in

• Module Scope – accessible in both scripting and designer, but only from the module it was created in For non-public encapsulation, if the relation is used where it is not supposed to be used, you get a build marker in Problems View.

Type Number

foreignDataSource

Qualified name of the foreign data source. Contains both the name of the foreign server and the name of the foreign table. It can be chosen from all of the available tables and has this format: "server-name.table-name". It can be any database table or view from any named server connection; it is not limited to the same database as the destination table.

At runtime, a related foundset will contain records from the destination table. NOTE: The destination table can be from a separate database than the source table. This is a powerful feature, but it is worth noting that a related foundset who's relation is defined across two databases will not be available when the source foundset is in find mode. This is because a related find requires a SQL JOIN, which cannot be issued across databases for all vendors.

Type String

Sample

'example_data.order_details'

initialSort

Foundsets, including related foundsets, have a sort property. By default, any foundset is sorted by the primary key(s) of the table upon which it is based.

Relations have an Initial Sort property, which overrides the default sort, such that any related foundset is initialized to use the sorting definition defined by the relation object. For more information see foundset sorting.

The value looks like "column_name asc, another_column_name desc, ...".

Type String

Sample

"productid asc"

joinType

The join type that is performed between the primary table and the foreign table. Can be "inner join" or "left outer join".

This SQL join is used when a find or a sort is performed using related criteria, and thus the join type will affect behavior in these situations.

• Inner Join - SQL Inner Join does not return any rows for parent records which have no related records. Therefore, if a sort or a find is performed when a related data provider is used for criterion, the related foundset may have records omitted due parents with no child records.

• Left Outer Join - SQL Left Outer Join will return always return a row for the parent record even if there are no related records. Therefore, if a sort or a find is performed when a related data provider is used for a criterion, the related foundset will include all matching records, regardless of the presence of related records.

Type Number

Sample

//Assume that the user chooses to sort a customer list containing 50 records. The sort is based on the account manager's last name, which is in the employees table. However, 3 of the customers don't have an employee listed to manage the account.
foundset.sort('customers_to_employees.last_name asc');
foundset.getSize(); //  returns 50 if the customers_to_employees relation specifies left outer join, 47 if the relation specifies inner join.

name

The name of the relation.

Type String

primaryDataSource

Qualified name of the primary data source. It contains both the name of the primary server and the name of the primary table. It can be any database table or view from any named server connection.

At runtime, a related foundset will exist in the context of a single record from the source table. For example, the relation 'customer_to_orders', will become available in the context of any record in a foundset which is based on the 'customers' table.

Type String

Sample

'example_data.customer'

---