Entity
レコードとテーブルの関係と同様に、エンティティ は データクラス のインスタンスです。 エンティティはデータクラスと同じ属性を持つほか、データ値や、特有のプロパティおよび関数を持ちます。
概要
.attributeName
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.attributeName : any
説明
データクラス属性はすべてエンティティのプロパティとして利用可能です。各エンティティのプロパティは、当該エンティティの属性値を格納します。
データクラス属性は [ ] を使用したシンタックスを使用することでもアクセス可能です。
この属性値タイプは属性の種類 (.kind; リレーションまたはストレージ) によります。
- attributeName で指定した属性がストレージ型の場合:
.attributeName
は attributeName と同じ型の値を返します。 - attributeName で指定した属性がリレートエンティティ型の場合:
.attributeName
はリレートエンティティを返します。 リレートエンティティの値は、ドット記法でプロパティを繋げることでアクセス可能です。例: "myEntity.employer.employees[0].lastname" - attributeName で指定した属性がリレートエ ンティティズ型の場合:
.attributeName
はリレートエンティティの新しいエンティティセレクションを返します。 重複しているエンティティは取り除かれます (返されるのは順列なしのエンティティセレクションです)。
例題
var $myEntity : cs.EmployeeEntity
$myEntity:=ds.Employee.new() // エンティティを新規作成します
$myEntity.name:="Dupont" // 'Dupont' を 'name' 属性に代入します
$myEntity.firstname:="John" // 'John' を 'firstname' 属性に代入します
$myEntity.save() // エンティティを保存します
.clone()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.clone() : 4D.Entity
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | 4D.Entity | <- | 同レコードを参照する新しいエンティティ |
説明
.clone()
関数は、対象エンティティと同じレコードを参照する新規エンティティをメモリ内に作成します。 このメソッドを使用するとエンティティを個別に更新することができます。
エンティティに対して何らかの変更をおこなった場合、それらは
.save( )
関数が実行されたときのみ、参照先のレコードに保存されるという点に注意してください。
この関数は、すでにデータベース に保存されているエンティティに対してのみ使用可能です。 新規に作成されたエンティティ(.isNew()
が true を返すもの) に対して呼び出すことはできません。
例題
var $emp; $empCloned : cs.EmployeeEntity
$emp:=ds.Employee.get(672)
$empCloned:=$emp.clone()
$emp.lastName:="Smith" // $emp に対する変更は $empCloned には適用されません
.diff()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.diff( entityToCompare : 4D.Entity { ; attributesToCompare : Collection } ) : Collection
引数 | 型 | 説明 | |
---|---|---|---|
entityToCompare | 4D.Entity | -> | 対象エンティティと比較するエンティティ |
attributesToCompare | Collection | -> | 比較する属性の名称 |
戻り値 | Collection | <- | エンティティ間の差異 |
説明
.diff()
関数は、二つのエンティティの中身を比較し、その差異を返します。
entityToCompare には、オリジナルのエンティティと比較をするエンティティを渡します。
attributesToCompare 引数で、比較する属性を 指定することができます。 これを渡した場合、指定された属性に対してのみ比較がおこなわれます。 省略時には、エンティティ間の差異がすべて返されます。
エンティティの差異は、以下のプロパティを持つオブジェクトのコレクションとして返されます:
プロパティ名 | 型 | 説明 |
---|---|---|
attributeName | String | 属性名 |
value | any - 属性の型による | オリジナルエンティティの属性値 |
otherValue | any - 属性の型による | entityToCompare の属性値 |
コレクションに含まれるのは異なる値を持っていた属性のみです。 差異が見つからない場合、diff()
は空のコレクションを返します。
この関数は、種類 (kind) が storage あるいは relatedEntity であるプロパティに適用されます。 リレート先のエンティティそのものが変更された場合 (外部キーの変更)、リレーションの名称とそのプライマリーキー名が attributeName プロパティに返されます (リレーション名についての value および otherValue は空になります)。
比較するどちらかのエンティティが Null である場合、エラーが生成されます。
例題 1
var $diff1; $diff2 : Collection
employee:=ds.Employee.query("ID=1001").first()
$clone:=employee.clone()
employee.firstName:="MARIE"
employee.lastName:="SOPHIE"
employee.salary:=500
$diff1:=$clone.diff(employee) // すべての差異が返されます
$diff2:=$clone.diff(employee;New collection("firstName";"lastName"))
// firstName と lastName についての差異のみが返されます
$diff1:
[
{
"attributeName": "firstName",
"value": "Natasha",
"otherValue": "MARIE"
},
{
"attributeName": "lastName",
"value": "Locke",
"otherValue": "SOPHIE"
},
{
"attributeName": "salary",
"value": 66600,
"otherValue": 500
}
]
$diff2:
[
{
"attributeName": "firstName",
"value": "Natasha",
"otherValue": "MARIE"
},
{
"attributeName": "lastName",
"value": "Locke",
"otherValue": "SOPHIE"
}
]
例題 2
var vCompareResult1; vCompareResult2; vCompareResult3; $attributesToInspect : Collection
vCompareResult1:=New collection
vCompareResult2:=New collection
vCompareResult3:=New collection
$attributesToInspect:=New collection
$e1:=ds.Employee.get(636)
$e2:=ds.Employee.get(636)
$e1.firstName:=$e1.firstName+" update"
$e1.lastName:=$e1.lastName+" update"
$c:=ds.Company.get(117)
$e1.employer:=$c
$e2.salary:=100
$attributesToInspect.push("firstName")
$attributesToInspect.push("lastName")
vCompareResult1:=$e1.diff($e2)
vCompareResult2:=$e1.diff($e2;$attributesToInspect)
vCompareResult3:=$e1.diff($e2;$e1.touchedAttributes())
vCompareResult1 (すべての差異が返されています):
[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
},
{
"attributeName": "salary",
"value": 33500,
"otherValue": 100
},
{
"attributeName": "employerID", // プライマリーキー名
"value": 117,
"otherValue": 118
},
{
"attributeName": "employer", // リレーション名
"value": "[object Entity]",// Company のエンティティ 117
"otherValue": "[object Entity]"// Company のエンティティ 118
}
]
vCompareResult2 ($attributesToInspect についての差異のみ返されます)
[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
}
]
vCompareResult3 ($e1 において更新された (touch された) 属性のみが返されます)
[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
},
{
"attributeName": "employerID", // プライマリーキー名
"value": 117,
"otherValue": 118
},
{
"attributeName": "employer", // リレーション名
"value": "[object Entity]",// Company のエン ティティ 117
"otherValue": "[object Entity]"// Company のエンティティ 118
}
]
.drop()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.drop( {mode : Integer} ) : Object
引数 | 型 | 説明 | |
---|---|---|---|
mode | Integer | -> | dk force drop if stamp changed : スタンプが 変更されていた場合でも強制的にドロップする |
戻り値 | Object | <- | ドロップの結果 |
説明
.drop()
関数は、データクラスに対応するテーブルにおいて、データストアのエンティティに格納されているデータを削除します。 エンティティそのものはメモリ内に残るという点に注意してください。
マルチユーザー、あるいはマルチプロセスアプリケーションにおいて、.drop()
関数は "オプティミスティック・ロック" 機構のもとで実行されます。これはレコードが保存されるたびに内部的なロックスタンプが自動的に増分していくという機構です。
mode 引数を渡さなかった場合のデフォルトでは、同エンティティが他のプロセスまたはユーザーによって変更されていた場合 (つまり、スタンプが変更されていた場合) にエラーを返します (以下参照)。
mode に dk force drop if stamp changed
オプションを渡すと、スタンプが変更されていてもエンティティはドロップされます (プライマリーキーは変わらない場合)。
戻り値
.drop( )
によって返されるオブジェクトには以下のプロパティが格納されます:
プロパティ | 型 | 説明 | |
---|---|---|---|
success | boolean | ドロップが成功した場合には true、それ以外は false | |
エラーの場合にのみ利用可能: | |||
status(*) | number | エラーコード、以下参照 | |
statusText(*) | text | エラーの詳細、以下参照 | |
ペシミスティック・ロックエラーの場合にのみ利用可能: | |||
lockKindText | text | "Locked by record" | |
lockInfo | object | ロック元についての情報 | |
task_id | number | プロセスID | |
user_name | text | マシン上でのセッションユーザー名 | |
user4d_alias | text | SET USER ALIAS で設定されていればユーザーエイリアス。それ以外は 4Dディレクトリのユーザー名 | |
host_name | text | マシン名 | |
task_name | text | プロセス名 | |
client_version | text | ||
深刻なエラーの場合にのみ利用可能 (深刻なエラーとは、プライマリーキーを重複させようとした、ディスクがいっぱいであった、などです): | |||
errors | Object の Collection | ||
message | text | エラーメッセージ | |
component signature | text | 内部コンポーネント署名 (例 "dmbg" はデータベースコンポーネントを表します) | |
errCode | number | エラーコード |
(*) エラ ー時には Result オブジェクトの status あるいは statusText プロパティに以下のいずれかの値が返されます:
定数 | 値 | 説明 |
---|---|---|
dk status entity does not exist anymore | 5 | エンティティはもうデータ内に存在していません。 このエラーは以下のような場合に起きえます:entity.lock() を使用するとき、このエラーは dk reload drop if stamp changed オプションを使用した場合に返されることがあります。 |
dk status locked | 3 | エンティティはペシミスティック・ロックでロックされています。 割り当てられた statusText: "Already locked" (既にロックされています) |
dk status serious error | 4 | 深刻なエラーとは、低レベルのデータベースエラー (例: 重複キー)、ハードウェアエラーなどです。 割り当てられた statusText: "Other error" (その他のエラー) |
dk status stamp has changed | 2 | エンティティの内部的なスタンプ値がデータ内に保存されているエンティティのものと合致しません (オプティミスティック・ロック)。entity.save() の場合: dk auto merge オプションが使用されていない場合に限りエラーentity.drop() の場合: dk force drop if stamp changed オプションが使用されていない場合に限りエラーentity.lock() の場合: dk reload if stamp changed オプションが使用されていない場合に限りエラー |
dk status wrong permission | 1 | 現在の権限では、エンティティを削除することはできません。 割り当てられた statusText: "Permission Error" (権限エラー) |
例題 1
dk force drop if stamp changed
オプションを使用しない例:
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
var $status : Object
$employees:=ds.Employee.query("lastName=:1";"Smith")
$employee:=$employees.first()
$status:=$employee.drop()
Case of
:($status.success)
ALERT($employee.firstName+" "+$employee.lastName+" をドロップしました。 ") // ドロップされたエンティティはメモリ内に残ります
:($status.status=dk status stamp has changed)
ALERT($status.statusText)
End case
例題 2
dk force drop if stamp changed
オプションを使用する例:
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
var $status : Object
$employees:=ds.Employee.query("lastName=:1";"Smith")
$employee:=$employees.first()
$status:=$employee.drop(dk force drop if stamp changed)
Case of
:($status.success)
ALERT($employee.firstName+" "+$employee.lastName+" をドロップしました。 ") // ドロップされたエンティティはメモリ内に残ります
:($status.status=dk status entity does not exist anymore)
ALERT($status.statusText)
End case
.first()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.first(): 4D.Entity
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | 4D.Entity | <- | エンティティセレクションの先頭エンティティへの参照 (見つからなければ null) |
説明
.first()
関数は、対象エンティティが所属するエンティティセレクションの先頭エンテ ィティへの参照を返します。
対象エンティティが所属する既存エンティティセレクションが存在しない場合 (つまり entity.getSelection( ) が Null を返す場合)、関数は Null値を返します。
例題
var $employees : cs.EmployeeSelection
var $employee; $firstEmployee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@") // このエンティティセレクションは 3件のエンティティを持ちます
$employee:=$employees[2]
$firstEmployee:=$employee.first() // $firstEmployee は、$employees エンティティセレクションの先頭エンティティです
.fromObject()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.fromObject( filler : Object )
引数 | 型 | 説明 | |
---|---|---|---|
filler | Object | -> | エンティティの属性値を設定するオブジェクト |
説明
.fromObject()
関数は、
filler に指定した内容でエンティティの属性値を設定します。
このコマンドは、元のエンティティを変更します。
オブジェクトとエンティティ間のマッピングは属性名でおこなわれます:
- オブジェクトのプロパティがデータクラスに存在しない場合、それは無視されます。
- データタイプは同じである必要があります。 オブジェク トとデータクラス間で型が合致しない場合、4D は可能であればデータを変換しようとし (
データタイプの変換
) 参照)、それ以外の場合にはその属性は更新されません。 - プライマリーキーはそのまま、あるいは "__KEY" プロパティを (プライマリーキー値とともに) 使って指定することができます。 その値のエンティティがデータクラス内に存在しない場合には、.save() が呼び出されたときに指定値を使ってエンティティが作成されます。 プライマリーキーを指定していない場合、エンティティは作成され、データベースのルールに基づいてプライマリーキー値が割り当てられます。 自動インクリメント機能はプライマリーキーが null の場合にのみ計算されます。
filler 引数のオブジェクトは、以下の条件のいずれかを満たしている場合にはリレートエンティティを扱うことができます:
- filler が外部キーを格納している
- filler が、リレートエンティティ名と同じ名称のプロパティを格納しており、その値であるオブジェクトは "__KEY" という名称の単一のプロパティを格納している
- リレートエンティティが存在しない場合、無視されます。
例題
以下のような $o オブジェクトがある場合:
{
"firstName": "Mary",
"lastName": "Smith",
"salary": 36500,
"birthDate": "1958-10-27T00:00:00.000Z",
"woman": true,
"managerID": 411,// リレートエンティティを主キー属性値で指定します
"employerID": 20 // リレートエンティティを主キー属性値で指定します
}
以下のコードを実行すると、manager および employerというリレートエンティティを持つエンティティを作成します。
var $o : Object
var $entity : cs.EmpEntity
$entity:=ds.Emp.new()
$entity.fromObject($o)
$entity.save()
また、オブジェクトとして提供されたリレートエンティティを使用することもできます:
{
"firstName": "Marie",
"lastName": "Lechat",
"salary": 68400,
"birthDate": "1971-09-03T00:00:00.000Z",
"woman": false,
"employer": {// リレートエンティティをオブジェクトで指定します
"__KEY": "21"
},
"manager": {// リレートエンティティをオブジェクトで指定します
"__KEY": "411"
}
}
.getDataClass()
履歴
リリース | 内容 |
---|---|
17 R5 | 追加 |
.getDataClass() : 4D.DataClass
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | 4D.DataClass | <- | エンティティが所属している DataClass オブジェクト |
説明
.getDataClass()
関数は、エンティティのデータクラスを返します。 この関数は汎用的なコードを書くのに有用です。