dataClass.fromCollection( )

Home

4D v19.8


dataClass.fromCollection ( objectCol {; settings} ) -> Result

Parameter	Type	Description
objectCol	Collection	Collection of objects to be mapped with entities
settings	Object	Build option: context
Result	EntitySelection	Entity selection filled from the collection

Description

The dataClass.fromCollection( ) method updates or creates entities in the dataclass according to the objectCol collection of objects, and returns the corresponding entity selection.

In the objectCol parameter, pass a collection of objects to create new or update existing entities of the dataclass. The property names must be the same as attribute names in the dataclass. If a property name does not exist in the dataclass, it is ignored. If an attribute value is not defined in the collection, its value will be null.

The mapping between the objects of the collection and the entities is done on the attribute names and matching types. If an object's property has the same name as an entity's attribute but their types do not match, the entity's attribute is not filled.

Create or update mode
For each object of objectCol:

If the object contains a boolean property "__NEW" set to false (or does not contain a boolean "__NEW" property), the entity is updated or created with the corresponding values of the properties from the object. No check is performed in regards to the primary key:
- If the primary key is given and exists, the entity is updated. In this case, the primary key can be given as is or with a "__KEY" property (filled with the primary key value).
- If the primary key is given (as is) and does not exist, the entity is created
- If the primary key is not given, the entity is created and the primary key value is assigned with respect to standard database rules.
If the object contains a boolean property "__NEW" set to true, the entity is created with the corresponding values of the attributes from the object. A check is performed in regards to the primary key:
- If the primary key is given (as is) and exists, an error is sent
- If the primary key is given (as is) and does not exist, the entity is created
- If the primary is not given, the entity is created and the primary key value is assigned with respect to standard database rules.
Note: The "__KEY" property containing a value is taken into account only when the "__NEW" property is set to false (or is omitted) and a corresponding entity exists. In all other cases, the "__KEY" property value is ignored, primary key value must be passed "as is".

Related entities
The objects of objectCol may contain one or more nested object(s) featuring one or more related entities, which can be useful to create or update links between entities.
The nested objects featuring related entities must contain a "__KEY" property (filled with the primary key value of the related entity) or the primary key attribute of the related entity itself. The use of a __KEY property allows independence from the primary key attribute name.

Note: The content of the related entities cannot be created / updated through this mechanism.

Stamp
If a __STAMP attribute is given, a check is performed with the stamp in the datastore and an error can be returned ("Given stamp does not match current one for record# XX of table XXXX"). For more information, see Entity locking.

settings

In the optional settings parameter, you can pass an object containing additional options. The following property is supported:

Property	Type	Description
context	Text	Label for the optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is designed for ORDA client/server processing; for more information, please refer to the Client/server optimization section.

Example 1

We want to update an existing entity. The __NEW property is not given, the employee primary key is given and exists:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=668 //Existing PK in Employee table

 $emp.firstName:="Arthur"

 $emp.lastName:="Martin"

 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company

  // For this employee, we can change the Company by using another existing PK in the related dataClass Company

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Example 2

We want to update an existing entity. The __NEW property is not given, the employee primary key is with the __KEY attribute and exists:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.__KEY:=1720 //Existing PK in Employee table

 $emp.firstName:="John"

 $emp.lastName:="Boorman"

 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company

  // For this employee, we can change the Company by using another existing PK in the related dataClass Company

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Example 3

We want to simply create a new entity from a collection:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.firstName:="Victor"

 $emp.lastName:="Hugo"

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Example 4

We want to create an entity. The __NEW property is True, the employee primary key is not given:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.firstName:="Mary"

 $emp.lastName:="Smith"

 $emp.employer:=New object("__KEY";121) //Existing PK in the related dataClass Company

 $emp.__NEW:=True

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Example 5

We want to create an entity. The __NEW property is omitted, the employee primary key is given and does not exist:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10000 //Unexisting primary key

 $emp.firstName:="Françoise"

 $emp.lastName:="Sagan"

 $empsCollection.push($emp)

 $employees:=ds.Employee.fromCollection($empsCollection)

Example 6

In this example, the first entity will be created and saved but the second will fail since they both use the same primary key:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$emp2;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10001 // Unexisting primary key

 $emp.firstName:="Simone"

 $emp.lastName:="Martin"

 $emp.__NEW:=True

 $empsCollection.push($emp)

 

 $emp2:=New object

 $emp2.ID:=10001 // Same primary key, already existing

 $emp2.firstName:="Marc"

 $emp2.lastName:="Smith"

 $emp2.__NEW:=True

 $empsCollection.push($emp2)

 $employees:=ds.Employee.fromCollection($empsCollection)

  //first entity is created

  //duplicated key error for the second entity