dataClass.fromCollection( )

4D v19.8


dataClass.fromCollection ( objectCol {; settings} ) -> 戻り値

引数	型	説明
objectCol	コレクション	エンティティにマップされるオブジェクトのコレクション
settings	オブジェクト	ビルドオプション: context
戻り値	EntitySelection	コレクションから値を受けたエンティティセレクション

説明

dataClass.fromCollection( ) メソッドはobjectCol 引数のオブジェクトのコレクションに準じてデータクラス内のエンティティを更新あるいは作成し、それに対応するエンティティセレクションを返します。

objectCol 引数には、オブジェクトのコレクションを渡し、新規エンティティを作成するか、データクラス内の既存のエンティティを更新します。プロパティ名はデータクラス内の属性名と同じである必要があります。プロパティ名がデータクラス内に存在しない場合、それは無視されます。コレクション内で属性の値が定義されていない場合、値はnull になります。

コレクションのオブジェクトとエンティティのマッピングは、属性名と型の合致をもって行われます。オブジェクトのプロパティがエンティティの属性と同じ名前を持っていたとしても、型が合致しない場合、エンティティの属性は空のままです。

作成モードと更新モード
objectCol 引数の各オブジェクトに対して:

オブジェクトがブール型の"__NEW" プロパティを含み、それがfalse に設定されている場合(あるいは"__NEW" プロパティが含まれていない場合)、エンティティはオブジェクト内の対応する値で更新あるいは作成されます。プライマリーキーに関するチェックは行われません:
- プライマリーキーが与えられていて存在する場合、エンティティは更新されます。この場合、プライマリーキーはそのまま与えられるか、"__KEY"プロパティ(ここのプライマリーキー値が渡されます)とともに与えられます。
- プライマリーキーがそのまま与えられているが存在しない場合、エンティティは作成されます。
- プライマリーキーが与えられていない場合、エンティティは作成され、プライマリーキー値は標準のデータベースのルールに基づいて割り当てられます。
  プライマリーキーは与えられたままの形式でも、__KEY プロパティを持っていても構いません。
オブジェクトがブール型の"__NEW" プロパティを含み、それがtrue に設定されている場合、エンティティはオブジェクト内の対応する値で作成されます。プライマリーキーに関するチェックが行われます:
- プライマリーキーがそのまま与えられていて存在する場合、エラーが返されます。
- プライマリーキーがそのまま与えられているが存在しない場合、エンティティは作成されます。
- プライマリーキーが与えられていない場合、エンティティは作成され、プライマリーキー値は標準のデータベースのルールに基づいて割り当てられます。
注: 値を格納している"__KEY" プロパティは、"__NEW" プロパティがfalse に設定されて(あるいは省略されて)いて、かつ対応するエンティティが存在する場合のみ、考慮されます。それ以外の場合には、"__KEY" プロパティ値は無視されるので、プライマリーキー値はそのまま渡さなければなりません。

リレートされたエンティティ
objectCol 引数内のオブジェクトは、リレートされたエンティティを格納しているオブジェクトを一つあるいは複数ネストすることができます。これはエンティティ間のリンクを作成あるいは更新するのに有用です。
リレートされたエンティティを格納しているネストされたオブジェクトは、___KEY 属性(プライマリーキーあるいはリレートされたエンティティを格納している必要があります)あるいはリレートされたエンティティ自身のプライマリーキーを格納している必要があります。属性を使用すると、プライマリーキー名に依存する必要がありません。

注: この機構を通してリレートされたエンティティの中身を作成/更新することはできません。

Stamp
プロパティが与えられている場合、データストア内のスタンプのチェックが行われ、エラーが返されることがあります("与えられたスタンプはテーブルXXX のレコード# XXのカレントのものと合致しません")。

settings

任意のsettings 引数には、追加のオプションを格納しているオブジェクトを渡すことができます。以下のプロパティがサポートされています:

プロパティ	型	詳細
context	テキスト	エンティティセレクションに適用されている最適化コンテキストのラベル。エンティティセレクションを扱うコードはこのコンテキストを使うことで最適化の恩恵を受けることができます。この機能はORDA のクライアント/サーバー処理を想定して設計されています。詳細については、クライアント/サーバーの最適化の章を参照ください。

例題 1

既存のエンティティを更新したい場合を考えます。__NEW プロパティはなく、従業員のプライマリーキーは存在していて判明しています:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=668 //Employee テーブルの既存のプライマリーキー

 $emp.firstName:="Arthur"

 $emp.lastName:="Martin"

 $emp.employer:=New object("ID";121) //リレートされたデータクラスCompany 内の既存のプライマリーキー

  // この従業員については、リレートされたデータクラスCompanyの他の既存のプライマリーキーを使用することでCompany を変更することができます

 $empsCollection.push($emp)

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

例題 2

既存のエンティティを更新したい場合を考えます。 __NEW プロパティは与えられてなく、employee プライマリーキーは __KEY 属性があり、存在しています:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.__KEY:=1720 //Employee テーブル内の既存のプライマリーキー

 $emp.firstName:="John"

 $emp.lastName:="Boorman"

 $emp.employer:=New object("ID";121) //リレートされたデータクラスCompany内の既存のプライマリーキー

  // この従業員に対しては、リレートされたデータクラスCompany 内の他の既存のプライマリーキーを使用することで会社を変更することができます

 $empsCollection.push($emp)

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

例題 3

シンプルにコレクションから新しいエンティティを作成したい場合を考えます:

 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)

例題 4

エンティティを作成したい場合を考えます。__NEW プロパティはTrue であり、employee のプライマリーキーは不明だとします:

 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) //リレートされたデータクラスCompamy 内の既存のプライマリーキー

 $emp.__NEW:=True

 $empsCollection.push($emp)

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

例題 5

エンティティを作成したい場合を考えます。__NEW プロパティは省略されていて、employee プライマリーキーは判明していますが、存在はしません:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10000 //存在しないプライマリーキー

 $emp.firstName:="Françoise"

 $emp.lastName:="Sagan"

 $empsCollection.push($emp)

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

例題 6

この例題では、最初のエンティティは問題なく作成されて保存されますが、2つめのエンティティは最初のと同じプライマリーキーを使用しているため失敗します:

 C_COLLECTION($empsCollection)

 C_OBJECT($emp;$emp2;$employees)

 

 $empsCollection:=New collection

 $emp:=New object

 $emp.ID:=10001 // 存在しないプライマリーキー

 $emp.firstName:="Simone"

 $emp.lastName:="Martin"

 $emp.__NEW:=True

 $empsCollection.push($emp)

 

 $emp2:=New object

 $emp2.ID:=10001 // 同じプライマリーキー、既に存在している

 $emp2.firstName:="Marc"

 $emp2.lastName:="Smith"

 $emp2.__NEW:=True

 $empsCollection.push($emp2)

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

  //最初のエンティティは作成されます

  //2つめのエンティティは重複キーエラーになります

参照

entitySelection.toCollection( )