DataStore
データストア とは、ORDA によって提供されるインターフェースオブジェクトです。データストアはデータベースへの参照とアクセスを提供します。 Datastore
オブジェクトは以下のコマンドによって返されます:
- ds: メインデータストアへのショートカット
- Open datastore: リモートデータストアを開きます
概要
ds
履歴
リリース | 内容 |
---|---|
18 | localID パラメーターをサポート |
17 | 追加 |
ds { ( localID : Text ) } : cs.DataStore
引数 | 型 | 説明 | |
---|---|---|---|
localID | Text | -> | 参照を取得したいリモートデータストアのローカルID |
戻り値 | cs.DataStore | <- | データストア参照 |
説明
ds
コマンドは、カレントの 4Dデータベース、または localID で指定したデータベースに合致するデータストアの参照を返します。
localID を省略した (または空の文字列 "" を渡した) 場合には、ローカル4Dデータベース (4D Server でリモートデータベースを開いている場合にはそのデータベース) に合致するデータストアの参照を返します。 データストアは自動的に開かれ、ds
を介して直接利用することができます。
開かれているリモートデータストアのローカルIDを localID パラメーターに渡すと、その参照を取得できます。 このデータストアは、あらかじめカレントデータベース (ホストまたはコンポーネント) によって Open datastore
コマンドで開かれている必要があります。 このコマンドを使用したときにローカルIDが定義されます。
ローカルIDのスコープは、当該データストアを開いたデータベースです。
localID に合致するデータストアが見つからない場合、コマンドは Null を返します。
cs.Datastore
が提供するオブジェクトは、ORDAマッピングルール に基づいて、ターゲットデータベースからマッピングされます。
例題 1
4Dデータベースのメインデータストアを使用します:
$result:=ds.Employee.query("firstName = :1";"S@")
例題 2
var $connectTo; $firstFrench; $firstForeign : Object
var $frenchStudents; $foreignStudents : cs.DataStore
$connectTo:=New object("type";"4D Server";"hostname";"192.168.18.11:8044")
$frenchStudents:=Open datastore($connectTo;"french")
$connectTo.hostname:="192.168.18.11:8050"
$foreignStudents:=Open datastore($connectTo;"foreign")
//...
//...
$firstFrench:=getFirst("french";"Students")
$firstForeign:=getFirst("foreign";"Students")
// getFirst メソッド
// getFirst(localID;dataclass) -> entity
#DECLARE( $localId : Text; $dataClassName : Text ) -> $entity : 4D.Entity
$0:=ds($localId)[$dataClassName].all().first()
Open datastore
履歴
リリース | 内容 |
---|---|
20 R6 | Qodly インスタンスへのアクセスをサポート |
20 R4 | 新しい passwordAlgorithm プロパティ |
18 | 追加 |
Open datastore( connectionInfo : Object ; localID : Text ) : cs.DataStore
引数 | 型 | 説明 | |
---|---|---|---|
connectionInfo | Object | -> | リモートデータストアへの接続に使用する接続プロパティ |
localID | Text | -> | ローカルアプリケーション内で、開かれたデータストアに対して割り当てる ID (必須) |
戻り値 | cs.DataStore | <- | データストアオブジェクト |
説明
Open datastore
コマンドは、
connectionInfo 引数が指定するリモートデータストアにアプリケーションを接続します。戻り値は、localID ローカルエイリアスに紐づけられた cs.DataStore
オブジェクトです。
以下のリモートデータストアが、このコマンドでサポートされています:
データストアの種類 | 説明 |
---|---|
リモート4Dアプリケーション | 次の条件を満たし、リモートデータストアとして利用可能な 4Dアプリケーション: |
Qodly アプリケーション | 定義されたロールに関連付けられた有効な APIキー と APIエンドポイント が提供されている Qodly Serverアプリケーション。 connectionInfo オブジェクトの api-key プロパティを使って APIキーを渡す必要があります。 その後、そのロールに付与された権限の範囲で、返されたデータストアオブジェクトを操作できます。 |
Open datastore
のリクエストは 4D REST API に依存し、リモートの 4D Server上で接続を開くにあたって、4D クライアントライセンスが必要な場合があります。 選択したカレントユーザーログインモードに応じて認証を構成する方法については、ユーザーログインモードのセクション を参照ください。
connectionInfo には、接続したいリモートデータストアの詳細を格納したオブジェクトを渡します。 オブジェクトは以下のプロパティを格納することができます (hostname を除き、すべてのプロパティは任意です):
プロパティ | 型 | リモート4Dアプリケーション | Qodly アプリケーション |
---|---|---|---|
hostname | Text | リモートデータストアの名前または IPアドレス + ":" + ポート番号 (ポート番号は必須) | Qodly クラウドインスタンスの APIエンドポイント |
user | Text | ユーザー名 | - (無視されます) |
password | Text | ユーザーパスワード | - (無視されます) |
idleTimeout | Longint | アクティビティがなかった場合に、セッションがタイムアウトするまでの時間 (分単位)。この時間を過ぎると、4D によって自動的にセッションが閉じられます。 省略時のデフォルトは 60 (1時間) です。 60 (分) 未満の値を指定することはできません (60 未満の値を渡した場合、タイムアウトは 60 (分) に設定されます)。 詳細については、セッションの終了 を参照ください。 | - (無視されます) |
tls | Boolean | セキュアな接続を使用する場合は true (1)。 省略時のデフォルトは false です。 可能なかぎり安全な接続を使用することが推奨されます。 | セキュアな接続を使用する場合は true。 省略時のデフォルトは false です。 |
type | Text | "4D Server" でなければなりません | - (無視されます) |
api-key | Text | - (無視されます) | Qodly クラウドインスタンスの APIキー |
(*) tls
が true である場合、以下の条件が満たされていれば、HTTPSプロトコルが使用されます:
- リモートデータストアで HTTPS が有効化されている。
- 指定されたポート番号は、データベース設定で設定されている HTTPS ポートと合致している。
- 4Dアプリケーションに有効な証明書と非公開暗号鍵がインストールされている。 条件を満たさない場合、エラー "1610 - ホスト xxx へのリモートリクエストに失敗しました" が生成されます。
localID 引数は、リモートデータストア上で開かれるセッションのローカルエイリアスです。 localID 引数の ID がすでにアプリケーションに存在している場合、その ID が使用されています。 そうでない場合、データストアオブジェクトが使用されたときに localID のセッションが新規に作成されます。
一旦セッションが開かれると、以下の 2行の宣言は同等のものとなり、同じデータストアオブジェクトへの参照を返します:
$myds:=Open datastore(connectionInfo;"myLocalId")
$myds2:=ds("myLocalId")
//$myds と $myds2 は同一のものです
cs.Datastore
が提供するオブジェクトは、ORDAマッピングルール に基づいてマッピングされます。
合致するデータストアが見つからない場合、Open datastore
は Null を返します。
例題 1
user / password を指定せずにリモートデータストアに接続します:
var $connectTo : Object
var $remoteDS : cs.DataStore
$connectTo:=New object("type";"4D Server";"hostname";"192.168.18.11:8044")
$remoteDS:=Open datastore($connectTo;"students")
ALERT("このリモートデータストアには "+String($remoteDS.Students.all().length)+" 名の生徒が登録されています")
例題 2
user / password / timeout / tls を指定してリモートデータストアに接続します:
var $connectTo : Object
var $remoteDS : cs.DataStore
$connectTo:=New object("type";"4D Server";"hostname";\"192.168.18.11:4443";\
"user";"marie";"password";$pwd;"idleTimeout";70;"tls";True)
$remoteDS:=Open datastore($connectTo;"students")
ALERT("このリモートデータストアには "+String($remoteDS.Students.all().length)+" 名の生徒が登録されています")
例題 3
複数のリモートデータストアと接続します:
var $connectTo : Object
var $frenchStudents; $foreignStudents : cs.DataStore
$connectTo:=New object("hostname";"192.168.18.11:8044")
$frenchStudents:=Open datastore($connectTo;"french")
$connectTo.hostname:="192.168.18.11:8050"
$foreignStudents:=Open datastore($connectTo;"foreign")
ALERT("フランスの生徒は "+String($frenchStudents.Students.all().length)+" 名です")
ALERT("外国の生徒は "+String($foreignStudents.Students.all().length)+" 名です")
例題 4
Qodly アプリケーションへの接続:
var $connectTo : Object:={hostname: "https://xxx-x54xxx-xx-xxxxx-8xx5-xxxxxx.xx-api.cloud.com"; tls: True}
var $remoteDS : 4D.DataStoreImplementation
var $data : 4D.EntitySelection
$connectTo["api-key"]:="fxxxx-xxxx-4xxx-txxx-xxxxxxxx0" // 実際にはハードコードせず
// APIキーを安全な場所 (ファイルなど) に保存し、
// コードで読み込むることが推奨されます
$remoteDS:=Open datastore($connectTo; "remoteId")
$data:=$remoteDS.item.all()
ALERT(String($data.length)+" 件の項目が読み込まれました")
エラー管理
エラーが起きた場合、コマンドは Null を返します。 リモートデータベースにアクセスできなかった場合 (アドレス違い、Webサーバーが開始されていない、http/https が有効化されていない、等)、エラー1610 "ホスト XXX へのリモートリクエストに失敗しました" が生成されます。 このエラーは ON ERR CALL
で実装されたメソッドで割り込み可能です。
.dataclassName
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.dataclassName : 4D.DataClass
説明
データストアの各データクラスは DataStore オブジェクト のプロパティとして利用可能です。 戻り値のオブジェクト には データクラスの詳細が格納されています。
例題
var $emp : cs.Employee
var $sel : cs.EmployeeSelection
$emp:=ds.Employee //$emp は Employeeデータクラスを格納します
$sel:=$emp.all() // 全従業員のエンティティセレクションを取得します
// あるいは以下のように直接書くことも可能です:
$sel:=ds.Employee.all()
.cancelTransaction()
履歴
リリース | 内容 |
---|---|
18 | 追加 |
.cancelTransaction()
引数 | 型 | 説明 | |
---|---|---|---|
引数を必要としません |
説明
.cancelTransaction()
関数は、指定データストアのカレントプロセスにおいて、.startTransaction()
によって開かれた トランザクションをキャンセルします。
.cancelTransaction()
関数は、トランザクション中におこなわれたデータ変更をすべてキャンセルします。
複数のトランザクションをネストすること (サブトランザクション) が可能です。 メイントランザクションがキャンセルされると、サブトランザクションも (たとえ個々に.validateTransaction()
関数で承認されていても) すべてキャンセルされます。
例題
.startTransaction()
関数の例題を参照ください。
.clearAllRemoteContexts()
履歴
リリース | 内容 |
---|---|
19 R5 | 追加 |
.clearAllRemoteContexts()
引数 | 型 | 説明 | |
---|---|---|---|
引数を必要としません |
説明
.clearAllRemoteContexts()
関数は、 データストアのすべてのアクティブコンテキストの全属性をクリアします。
この機能は主にデバッグで使用されます。 注意しなければならないのは、デバッガーを開くと、デバッガーはサーバーにリクエストを送り、データクラス属性をす べてクエリして表示することです。 このため、不要なデータでコンテキストが過負荷になることがあります。
そのような場合は、.clearAllRemoteContexts()
を使用してコンテキストをクリアし、クリーンな状態を保つことができます。
参照
.getRemoteContextInfo()
.getAllRemoteContexts()
.setRemoteContextInfo()
.encryptionStatus()
履歴
リリース | 内容 |
---|---|
17 R5 | 追加 |
.encryptionStatus(): Object
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Object | <- | カレントデータストアと、各テーブルの暗号化についての情報 |
説明
.encryptionStatus()
関数は、カレントデータファイルの暗号化状態を示すオブジェクトを返します。カレントデータファイルとはつまり、ds
データストアのデータファイルです。 各テーブルの状態も提供されます。
その他のデータファイルの暗号化状態を調べるには、
Data file encryption status
コマンドを使います。
戻り値
戻り値のオブジェクトには、以下のプロパティが格納されています:
プロパティ | 型 | 説明 | ||
---|---|---|---|---|
isEncrypted | Boolean | データファイルが暗号化されていれば true | ||
keyProvided | Boolean | 暗号化されたデータファイルに合致する暗号化キーが提供されていれば true (*) | ||
テーブル | Object | 暗号化可能および暗号化されたテーブルと同じ数のプロパティを持つオブジェクト | ||
tableName | Object | 暗号化可能または暗号化されたテーブル | ||
name | Text | テーブル名 | ||
num | Number | テーブル番号 | ||
isEncryptable | Boolean | ストラクチャーファイルにおいて、テーブルが暗号化可能と宣言されていれば true | ||
isEncrypted | Boolean | データファイルにおいて、テーブルのレコードが暗号化されていれば true |
(*) 暗号化キーは、以下の手段のいずれかで提供されます:
.provideDataKey()
コマンド- データストアを開く前に接続されていたデバイスのルート
Discover data key
コマンド
例題
カレントデータファイル内で暗号化されているテーブルの数を知りたい場合:
var $status : Object
$status:=ds.encryptionStatus()
If($status.isEncrypted) // データベースが暗号化されていれば
C_LONGINT($vcount)
C_TEXT($tabName)
For each($tabName;$status.tables)
If($status.tables[$tabName].isEncrypted)
$vcount:=$vcount+1
End if
End for each
ALERT("データベースには "+String($vcount)+" 件の暗号化されたテーブルが存在しています。")
Else
ALERT("このデータベースは暗号化されていません。")
End if
.flushAndLock()
履歴
|リリース|変更内容|
|---|---| |20|追加|
.flushAndLock()
引数 | 型 | 説明 | |
---|---|---|---|
引数を必要としません |
説明
.flushAndLock()
関数は、ローカルデータストアのキャッシュをフラッシュし、データベースに対して他のプロセスが書き込み操作をおこなうのを防ぎます。 これにより、データストアは凍結状態におかれます。 この関数は、たとえばアプリケーションのスナップショットを実行する前に呼び出す必要があります。
この関数は次の場合にのみ使えます:
- ローカルデータストア (
ds
) を対象に。 - クライアント/サーバー環境では、サーバーマシン上にて。
この関数が実行されると、他のすべてのプロセスで .save()
などの書き込み操作や、追加の .flushAndLock()
の呼び出しが凍結され、データストアのロックが解除されるまで続きます。
同一プロセス内で .flushAndLock()
を複数回呼び出した場合、データストアのロック を解除するには、同じ回数だけ .unlock()
を呼び出す必要があります。
データストアのロックが解除されるのは、以下の場合です:
- 同プロセス内で
.unlock()
関数が呼び出された場合、または .flushAndLock()
関数を呼び出したプロセスが終了した場合。
データストアがすでに他のプロセスからロックされている場合、.flushAndLock()
の呼び出しは凍結され、データストアのロックが解除されたときに実行されます。
.flushAndLock()
関数が実行できない場合 (リモートの 4D で実行された場合など) には、エラーが発生します。
例題
データフォルダーとともにカレントジャーナルファイルのコピーを作成します:
$destination:=Folder(fk documents folder).folder("Archive")
$destination.create()
ds.flushAndLock() // 他のプロセスからの書き込み操作をブロックします
$dataFolder:=Folder(fk data folder)
$dataFolder.copyTo($destination) // データフォルダーをコピーします
$oldJournalPath:=New log file // ジャーナルを閉じて、新しいものを作成します
$oldJournal:=File($oldJournalPath; fk platform path)
$oldJournal.moveTo($destination) // 閉じたジャーナルを保存します
ds.unlock() // コピー操作をおこなったので、データストアのロックを解除します
参照
.getAllRemoteContexts()
履歴
リリース | 内容 |
---|---|
19 R5 | 追加 |
.getAllRemoteContexts() : Collection
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Collection | <- | 最適化コンテキストオブジェクトのコレクション |
上級者向け: この機能は、特定の構成のため、ORDAのデフォルト機能をカスタマイズする必要がある開発者向けです。 ほとんどの場合、使用する必要はないでしょう。
説明
.getAllRemoteContexts()
関数は、データストア内のすべてのアクティブな最適化コンテキストに関する情報を格納するオブジェクトのコレクションを返します。
コンテキストの作成に関する詳細については、クライアント/サーバーの最適化 を参照ください。
返されたコレクション内の各オブジェクトは、.getRemoteContextInfo()
セクションに記載されているプロパティを持ちます。
例題
次のコードは 2つのコンテキストを設定し、.getAllRemoteContexts()
を使用してそれらを取得します:
var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $addresses : cs.AddressSelection
var $p : cs.PersonsEntity
var $a : cs.AddressEntity
var $contextA; $contextB : Object
var $info : Collection
var $text : Text
// リモートデータストアを開きます
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
// コンテキストA を設定します
$contextA:=New object("context"; "contextA")
$persons:=$ds.Persons.all($contextA)
$text:=""
For each ($p; $persons)
$text:=$p.firstname+" lives in "+$p.address.city+" / "
End for each
// コンテキストB を設定します
$contextB:=New object("context"; "contextB")
$addresses:=$ds.Address.all($contextB)
$text:=""
For each ($a; $addresses)
$text:=$a.zipCode
End for each
// すべてのリモートコンテキストを取得します (contextA と contextB)
$info:=$ds.getAllRemoteContexts()
//$info = [{name:"contextB"; dataclass:"Address"; main:"zipCode"},
{name:"contextA";dataclass:"Persons";main:"firstname,address.city"}]
この例はデモンストレーションであり、実際の実装を想定したものではありません。
参照
.getRemoteContextInfo()
.setRemoteContextInfo()
.clearAllRemoteContexts()
.getGlobalStamp()
履歴
リリース | 内容 |
---|---|
20 R3 | 追加 |
.getGlobalStamp() : Real
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Real | <- | グローバル変更スタンプのカレント値 |
説明
.getGlobalStamp()
関数は、データストアのグローバル変更スタンプのカレント値を返します。
この関数は次の場合にのみ使えます:
- ローカルデータストア (
ds
) を対象に。 - クライアント/サーバー環境では、サーバーマシン上にて。
グローバルスタンプとデータ変更追跡の詳細については、グロ ーバルスタンプの使い方 を参照ください。
例題
var $currentStamp : Real
var $hasModifications : Boolean
$currentStamp:=ds.getGlobalStamp()
methodWhichCouldModifyEmployees // なんらかのコード
$hasModifications:=($currentStamp # ds.getGlobalStamp())
参照
.getInfo()
履歴
リリース | 内容 |
---|---|
17 | 追加 |
.getInfo(): Object
引数 | 型 | 説明 | |
---|---|---|---|
戻り値 | Object | <- | データストアのプロパティ |
説明
.getInfo()
関数は、データストアの情報を提供するオブジェクトを返します。 このメソッドは汎用的なコードを書くのに有用です。
返されるオブジェクト
プロパティ | 型 | 説明 | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | ||||||||||||||||
networked | boolean | ||||||||||||||||
localID | text | マシン上のデータストアID。 これは、Open datastore コマンドで返される localId 文字列です。 メインデータストアの場合は空の文字列 ("") です。 | |||||||||||||||
connection | object | リモートデータストア接続の情報を格納したオブジェクト (メインデータストアの場合は返されません)。 次のプロパティを含みます:
|
.getInfo()
関数が、4D Server またはシングルユーザー版 4D 上で実行された場合、networked
は false となります。.getInfo()
関数が、リモート版 4D 上で実行された場合、networked
は true となります。
例題 1
var $info : Object
$info:=ds.getInfo() // 4D Server または 4D 上で実行した場合
//{"type":"4D","networked":false,"localID":""}
$info:=ds.getInfo() // リモート版4D 上で実行した場合
//{"type":"4D","networked":true,"localID":""}