エンティティ
レコードとテーブルの関係と同様に、エンテ ィティ は データクラス のインスタンスです。 エンティティはデータクラスと同じ属性を持つほか、データ値や、特有のプロパティおよび関数を持ちます。
概要
.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()
関数は、エンティティのデータクラスを返します。 この関数は汎用的なコードを書くのに有用です。
例題
以下の汎用的なコー ドは、あらゆるエンティティを複製します:
// duplicate_entity メソッド
// duplicate_entity($entity)
#DECLARE($entity : 4D.Entity)
var $entityNew : 4D.Entity
var $status : Object
$entityNew:=$entity.getDataClass().new() // 親データクラスに新しいエンティティを作成します
$entityNew.fromObject($entity.toObject()) // 全属性を取得します
$entityNew[$entity.getDataClass().getInfo().primaryKey]:=Null // プライマリーキーをリセットします
$status:=$entityNew.save() // 複製したエンティティを保存します
.getKey()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.getKey( { mode : Integer } ) : Text
.getKey( { mode : Integer } ) : Integer
引数 | 型 | 説明 | |
---|---|---|---|
mode | Integer | -> | dk key as string : プライマリーキーの型にかかわらず、プライマリーキーを文字列として返します |
戻り値 | Text | <- | エンティティのテキスト型プライマリーキーの値 |
戻り値 | Integer | <- | エンティティの数値型プライマリーキーの値 |
説明
.getKey()
関数は、エンティティのプライマリーキー値を返します。
プライマリーキーは数値 (倍長整数) あるいは文字列です。 mode 引数として dk key as string
オプションを渡すことで、実際のプライマリーキーの型に関係なく、返されるプライマリーキー値の型を文字列に "強制" することができます。
例題
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName=:1";"Smith")
$employee:=$employees[0]
ALERT("プライマリーキー: "+$employee.getKey(dk key as string))
.getRemoteContextAttributes()
履歴
リリース | 内容 |
---|---|
19R5 | 追加 |
.getRemoteContextAttributes() : Text
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Text | <- | エンティティにリンクされたコンテキスト属性 (カンマ区切り) |
上級者向け: この機能は、特定の構成のため、ORDAのデフォルト機能をカスタマイズする必要がある開発者向けです。 ほとんどの場合、使用する必要はないでしょう。
説明
.getRemoteContextAttributes()
関数は、 エンティティによって使われている最適化コンテキストの情報を返します 。
エンティティについて 最適化コンテキスト が存在しない場合、関数は空のテキストを返します。
例題
var $ds : 4D.DataStoreImplementation
var $address : cs.AddressEntity
var $p : cs.PersonsEntity
var $contextA : Object
var $info : Text
var $text : Text
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
$contextA:=New object("context"; "contextA")
$address:=$ds.Address.get(1; $contextA)
$text:=""
For each ($p; $address.persons)
$text:=$p.firstname+" "+$p.lastname
End for each
$info:=$address.getRemoteContextAttributes()
//$info = "persons,persons.lastname,persons.firstname"
参照
EntitySelection.getRemoteContextAttributes()
.clearAllRemoteContexts()
.getRemoteContextInfo()
.getAllRemoteContexts()
.setRemoteContextInfo()
.getSelection()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.getSelection(): 4D.EntitySelection
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | 4D.EntitySelection | <- | エンティティが所属するエンティティセレクション (見つからなければ null) |
説明
.getSelection()
関数は、エンティティが所属するエンティティ セレクションを返します。
対象エンティティがエンティティセレクションに所属していない場合、関数は Null値を返します。
例題
var $emp : cs.EmployeeEntity
var $employees; $employees2 : cs.EmployeeSelection
$emp:=ds.Employee.get(672) // エンティティセレクションに属していないエンティティです
$employees:=$emp.getSelection() // $employees は Null です
$employees2:=ds.Employee.query("lastName=:1";"Smith") // このエンティティセレクションは 6件のエンティティを格納しています
$emp:=$employees2[0] // エンティティセレクションに所属しているエンティティです
ALERT("エンティティセレクションには "+String($emp.getSelection().length)+" 件のエンティティが含まれています")
.getStamp()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.getStamp() : Integer
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Integer | <- | エンティティのスタンプ (エンティティが作成されたばかりの場合には 0) |
説明
.getStamp()
関数は、 エンティティのスタンプの値を返します。
内部スタンプは、エンティティが保存されるたびに 4D によって自動的にインクリメントされます。 これは同じエンティティに対する複数のユーザーの同時アクセス・編集を管理します。この機構の詳細については、エンティティロッキング を参照ください。
(一度も保存されていない) 新規エンティティに対しては、このメソッドは 0 を返します。 しかしながら、エンティティがまだ作成されたばかりかどうかを調べるには、isNew() の使用が推奨されます。
例題
var $entity : cs.EmployeeEntity
var $stamp : Integer
$entity:=ds.Employee.new()
$entity.lastname:="Smith"
$entity.save()
$stamp:=$entity.getStamp() //$stamp=1
$entity.lastname:="Wesson"
$entity.save()
$stamp:=$entity.getStamp() //$stamp=2
.indexOf()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.indexOf( { entitySelection : 4D.EntitySelection } ) : Integer
引数 | 型 | 説明 | |
---|---|---|---|
entitySelection | 4D.EntitySelection | -> | エンティティの位置を取得する対象のエンティティセレクション |
戻り値 | Integer | <- | エンティティセレクション内でのエンティティの位置 |
説明
.indexOf()
関数は、エンティティセレクション内におけるエンティティの位置を返します。
entitySelection 引数が渡されなかった場合はデフォルトで、所属エンティティセレクション内でのエンティティの位置が返されます。 entitySelection 引数を渡した場合は、指定されたエンティティセレクション内でのエンティティの位置を返します。
戻り値は、0 と、エンティティセレクションの length より 1 を引いた値の範囲内の数値です。
- エンティティがエンティティセレクションを持たない場合、あるいは entitySelection 引数で指定したエンティティセレクションに含まれていない場合には、-1 が返されます。
- entitySelection 引数で指定したエンティティセレククションが Null である、あるいはエンティティと同じデータクラスのものでない場合には、エラーが生成されます。
例題
var $employees : cs.EmployeeSelection
var $employee : cs.EmployeeEntity
$employees:=ds.Employee.query("lastName = :1";"H@") // このエンティティセレクションには 3件のエンティティが格納されています
$employee:=$employees[1] // このエンティティはエンティティセレクションに所属しています
ALERT("The index of the entity in its own entity selection is "+String($employee.indexOf())) // 1
$employee:=ds.Employee.get(725) // エンティティセレクションに所属していないエンティティです
ALERT("The index of the entity is "+String($employee.indexOf())) // -1
.isNew()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.isNew() : Boolean
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Boolean | <- | エンティティが作成されたばかりで未保存の場合は true。 それ以外は false。 |
説明
.isNew()
関数は、対象エンティティが作成されたばかりで、まだデータストアに保存されていない場合に true を返します。 そうでない場合には、false を返します。