JSONStore API の概念

JSONStore は、Cordova Android アプリケーション、iOS アプリケーション、Windows 8 Universal アプリケーション、ならびにネイティブ Android アプリケーションおよびネイティブ iOS アプリケーションのための API 参照情報を提供します。

ストア

コレクションのオープンと初期化

1 つ以上のコレクションを開始します。 JSONStore コレクションを開始またはプロビジョニングすると、コレクションおよびドキュメントを収めるために使用される永続ストレージが存在しなければ、それが作成されることになります。 ストアが暗号化されている場合、正しいパスワードが渡されると、データをアクセス可能にするために必要なセキュリティー・プロシージャーが実行されます。 必要最小限の作業で、アプリケーションの開始時にすべてのコレクションを初期化することができます。

コレクションを開くと、そのコレクションに対してアクセサーが使用可能になります。これにより、コレクション API にアクセスできるようになります。 アクセサーにより、開発者は、初期化されたコレクションに対して find、add、replace などの関数を呼び出すことができます。

異なるコレクションを使用して、初期化を複数回行うことが可能です。 既に初期化されているコレクションに影響を与えることなく、新しいコレクションが初期化されます。

破棄

すべてのユーザーのデータを完全にワイプし、内部ストレージを破棄して、セキュリティー成果物をクリアします。destroy 関数は、以下のデータを除去します。

すべて閉じる

ストア内のすべてのコレクションへのアクセスを、それらのコレクションが再初期化されるまでロックします。initialize をログインとみなすことができる場合、close はログアウトとみなすことができます。

トランザクションの開始、コミット、およびロールバック

トランザクションは、いくつかの操作の集合であり、これらの操作がストアを対象として扱うようになるためにはすべての操作が成功しなければならないものです。 もし操作がどれか失敗した場合は、トランザクションがロールバックされてストアは前の状態に戻ることができます。 トランザクションの開始後は、余分な処理が行われないようにトランザクションのコミットまたはロールバックを扱うことが重要です。 トランザクション用に次の 3 つの操作が Store API に存在します。
  • トランザクションの開始
    トランザクションが失敗した場合にストアの状態が戻されるスナップショットを開始します。
  • トランザクションのコミット
    トランザクション内のすべての操作が成功したことをストアに通知します。すべての変更は、最終的なものとして確定することができます。
  • トランザクションのロールバック
    トランザクション内の 1 つの操作が失敗したことをストアに通知します。すべての変更は、廃棄する必要があります。
注: マルチスレッド化されたトランザクションに関するシステムの制限のため、Cordova アプリケーション用の Android 2.3.x ではトランザクションはサポートされていません。Android 2.3.x の Cordova アプリケーションでトランザクションを使用するには、トランザクションのコードの実行にネイティブ Android の JSONStore API を使用する Cordova プラグインを作成できます。マルチスレッド化されたトランザクションは Android 2.3.x では正しく機能しないため、トランザクション全体を同じスレッドで実行する必要があります。

コレクション

ドキュメントの保管および追加

ドキュメントまたはドキュメントの配列をコレクションに追加できます。 単一のオブジェクトではなくオブジェクトの配列 (例えば [{name: 'carlos'}, {name: 'tim'}]) を渡すこともできます。 配列内のすべてのオブジェクトは、コレクション内に新しいドキュメントとして保管されます。

ドキュメントの除去

1 つ以上のドキュメントをコレクションから除去するものとしてマーク付けします。 除去されたドキュメントは、find または count 操作によって返されません。

すべてのドキュメントの検索、ID によるドキュメントの検索、および照会による検索

コレクション内のドキュメントは、その検索フィールドおよび追加の検索フィールドを使用して検索することができます。 内部検索フィールド _id には、ドキュメントの検索 (ID による検索) に使用できる固有の整数 ID が入っています 。 以下の API を使用してドキュメントを検索できます。
  • すべてのドキュメントの検索
    コレクション内のすべてのドキュメントを返します。
  • すべてのダーティー・ドキュメントの検索
    コレクション内のダーティーとマーク付けされているすべてのドキュメントを返します。
  • ID による検索
    対応する _id 検索キー値を持つドキュメントを検索します。
  • 照会または照会部分による検索
    照会またはすべての照会部分に一致するすべてのドキュメントを検索します。詳しくは、追加参照 の『検索照会の形式』セクションを参照してください。
フィルターは、索引付けされているものを返します。これは、コレクションに保管されているものと異なる場合があります。 予期しない結果の例をいくつか次に示します。
  1. 検索フィールドに大文字がある場合でも、結果はすべて小文字で返されます。
  2. ストリング以外のものを渡した場合、それはストリングとして索引付されます。 例えば、1 は '1'、1.0 は '1.0'、true は '1'、false は '0' です。
  3. フィルター基準に最上位でない検索フィールドが含まれる場合、特殊 ID -@-) で結合されたすべての条件を持つ単一のストリングを取得することがあります。例えば、'carlos-@-mike-@-dgonz' となります。

ドキュメントの置き換えおよびドキュメントの変更

Replace API を使用すると、コレクション内のドキュメントの内容を _id に基づいて新しいデータに置き換えることができます。 データにデータベース内のドキュメントの _id フィールドが含まれる場合、そのドキュメントはそのデータに置き換えられ、そのドキュメントのすべての検索フィールドが再索引付けされます。

Change API は Replace API と似ています。ただし、Change は _id ではなく、1 セットの検索フィールド基準に基づいています。 Replace API は、_id のみからなる検索フィールド基準を使用して Change API を実行することでエミュレートすることができます。 ストア内のドキュメント、および Change API に渡されるデータには、検索フィールド基準のすべての検索フィールドが存在する必要があります。

すべてのドキュメントのカウント、すべてのダーティー・ドキュメントのカウント、および照会によるカウント

Count API は、照会に一致するドキュメントの合計数をカウントして整数を返します。 以下の 3 つの Count API があります。
  • Count All Documents
    コレクション内のすべてのドキュメントの合計数を示します。
  • Count All Dirty Documents
    コレクション内の現在ダーティーとマーク付けされているドキュメントの合計数を示します。
  • Count With Query or Query Parts
    特定の検索照会に一致するドキュメントの合計数を示します。 詳しくは、追加参照 の『検索照会の形式』セクションを参照してください。

コレクションの除去およびコレクションのクリア

コレクションを除去すると、コレクションに関連したすべてのデータが削除され、コレクション・アクセサーは使用できなくなります。

コレクションをクリアすると、コレクション内のすべてのドキュメントが削除されます。 この操作は、その完了後もコレクションを開いたままにします。

マーク消去

Mark Clean API は、コレクション内のドキュメントからダーティー・フラグを除去するために使用され、ドキュメントがドキュメント除去操作によってダーティーとマーク付けされていれば、そのドキュメントをコレクションから完全に削除します。 Mark Clean API は、コレクションをリモート・データベースと同期するために Find All Dirty Documents API と一緒に使用すると便利です。

追加参照

検索照会形式

API が検索照会を必要とする場合、コレクションに対して従う共通形式があります。 照会は、キー/値のペアのそれぞれがすべて AND 関係になっているオブジェクトの配列から構成されます。 配列内の各オブジェクトは、OR 関係になっています。 例えば、以下のようにします。
[{fn: "Mike", age: 30}, {fn: "Carlos", age: 36}]
これは、以下として表現されます (ファジー検索を使用)。
(fn LIKE "%Mike%" AND age LIKE "%30%") OR (fn LIKE "%Carlos%" AND age LIKE "%36%")

検索照会部分の形式

以下の例では、照会部分がどのように機能するかを示す疑似コードを使用しています。 {name: 'carlos', age: 10} などの照会には、{exact: true} などの修飾子を渡すことができます。これにより、名前と年齢に正確に一致する項目のみが返されるようになります。 照会部分を使用すると、照会のどの部分に修飾子を追加する際にも柔軟性が得られます。 例えば、以下のようにします。
queryPart1 = QueryPart().like('name', 'carlos').lessThan('age', 10);
先に示した例は、以下のようなものに変換されます。 
('name' LIKE %carlos%)  AND (age < 10)
別の照会部分を作成することもできます。例えば、以下のようになります。
queryPart2 = QueryPart().equal('name', 'mike')
例えば、find API を使用してさまざまな照会部分を追加するとします。
find([queryPart1, queryPart2]
結果は以下のようになります。
( ('name' LIKE %carlos%) AND (age < 10) ) OR (name EQUAL 'mike')

制限およびオフセット

API のオプションに制限を渡すと、結果の数が指定した数で制限されます。 またオフセットを渡して、指定した数だけ結果をスキップすることもできます。 オフセットを渡すには、制限も渡す必要があります。 この API は、ページ編集を実装する場合や最適化を行う場合に便利です。 データを必要なサブセットに制限すると、必要なメモリーおよび処理能力の節約になります。

ファジー検索と完全一致検索

デフォルトの振る舞いはファジー検索です。この場合、照会で部分的な結果が返されます。 例えば、照会 {name: 'carl'} では 'carlos' および 'carl' が検索されます (例えば name LIKE '%carl%')。{exact: true} が渡されると、完全一致となりますが、大/小文字の区別はありません。 'hello' は 'Hello' と一致します (例えば name.toLowerCase() = 'hello')。 整数マッチングは型を区別しません。例えば "1" は "1" と "1.0" の両方と一致します。数値は、10 進表記として保管されます。 例えば "1" は "1.0" として保管されます。 ブール値は 1 (true) および 0 (false) として索引付けされます。

親トピック: JSONStore