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 R4 | 新しい passwordAlgorithm プロパティ |
18 | 追加 |
Open datastore( connectionInfo : Object ; localID : Text ) : cs.DataStore
引数 | 型 | 説明 | |
---|---|---|---|
connectionInfo | Object | -> | リモートデータストアへの接続に使用する接続プロパティ |
localID | Text | -> | ローカルアプリケーション内で、開かれたデータストアに対して割り当てる ID (必須) |
戻り値 | cs.DataStore | <- | データストアオブジェクト |
説明
Open datastore
コマンドは、
connectionInfo 引数が指定する 4Dデータベースにアプリケーションを接続します。戻り値は、localID ローカルエイリアスに紐づけられた cs.DataStore
オブジェクトです。
connectionInfo で指定する 4Dデータベースはリモートデーターストアとして利用可能でなければなりません。 つまり、以下の条件を満たしている必要があります:
- データベースの Webサーバーは、http または https が有効化された状態で開始されていなければなりません。
- データストアは、RESTサーバーとして公開 オプションがチェックされている必要があります。また、データクラスと属性 も公開されている必要があります。
Open datastore
のリクエストは 4D REST API に依存し、接続を開くために 4D クライアントライセンスが必要な場合があります。 選択したカレントユーザーログインモードに応じて認証を構成する方法については、ユーザーログインモードのセクション を参照ください。
合致するデータベースが見つからない場合、Open datastore
は Null を返します。
localID 引数は、リモートデータストア上で開かれるセッションのローカルエイリアスです。 localID 引数の ID がすでにアプリケーションに存在している場合、その ID が使用されています。 そうでない場合、データストアオブジェクトが使用されたときに localID のセッションが新規に作成されます。
cs.Datastore
が提供するオブジェクトは、ORDAマッピングルール に基づいて、ターゲットデータベースからマッピングされます。
一旦セッションが開かれると、以下の 2行の宣言は同等のものとなり、同じデータストアオブジェクトへの参照を返します:
$myds:=Open datastore(connectionInfo;"myLocalId")
$myds2:=ds("myLocalId")
//$myds と $myds2 は同一のものです
connectionInfo には、接続したいリモートデータストアの詳細を格納したオブジェクトを渡します。 hostname を除くすべてのプロパティは任意です:
プロパティ | 型 | 説明 |
---|---|---|
hostname | Text | リモートデータストアの名前または IPアドレス + ":" + ポート番号 (ポート番号は必須) |
user | Text | ユーザー名 |
password | Text | ユーザーパスワード。 デフォルトでは、パスワードは平文で送信されるため、tls プロパティに true を渡して暗号化通信を使用することが 強く推奨されます。 |
idleTimeout | Longint | アクティビティがなかった場合に、セッションがタイムアウトするまでの時間 (分単位)。この時間を過ぎると、4D によって自動的にセッションが閉じられます。 省略時のデフォルトは 60 (1時間) です。 60 (分) 未満の値を指定することはできません (60 未満の値を渡した場合、タイムアウトは 60 (分) に設定されます)。 詳細については、セッションの終了 を参照ください。 |
tls | Boolean | 安全な接続を使用します(*) 。 省略時のデフォルトは false です。 可能なかぎり安全な接続を使用することが推奨されます。 |
passwordAlgorithm | Text | Validate password コマンドで digest パラメーターを true に設定してサーバーがパスワードを検証する場合は、"4d-rest-digest" を指定します。 |
type | Text | "4D Server" でなければなりません |
(*) tls が true だった場合、以下の条件が満たされていれば、HTTPSプロトコルが使用されます:
- リモートデータストアで HTTPS が有効化されている。
- 指定されたポート番号は、データベース設定で設定されている HTTPS ポートと合致している。
- データベースに有効な証明書と非公開暗号鍵がインストールされている。 条件を満たさない場合、エラー "1610 - ホスト xxx へのリモートリクエストに失敗しました" が生成されます。
例題 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)+" 名です")
エラー管理
エラーが起きた場合、コマンドは 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()
セクションに記載されているプロパティを持ちます。