JSONStore のトラブルシューティング

概説

以下に、JSONStore API を使用する際に発生する可能性がある問題を解決するために役立つ情報を記載しています。

ヘルプ要求をする際の情報提供

提供する情報が不足するリスクを負うよりも、多くの情報を提供することをお勧めします。 以下のリストは、JSONStore の問題に関してサポートを受けるために必要な情報の出発点と考えてください。

• オペレーティング・システムおよびバージョン。 例えば、Windows XP SP3 Virtual Machine や Mac OSX 10.8.3。
• Eclipse のバージョン。 例えば、Eclipse Indigo 3.7 Java EE。
• JDK のバージョン。 例えば、Java SE Runtime Environment (ビルド 1.7)。
• Mobile Foundation のバージョン。 例えば、IBM Worklight V5.0.6 Developer Edition。
• iOS のバージョン。 例えば、iOS Simulator 6.1 や iPhone 4S iOS 6.0 (非推奨。『非推奨となった機能および API エレメント』を参照)。
• Android のバージョン。 例えば、Android Emulator 4.1.1 や Samsung Galaxy Android 4.0 API Level 14。
• Windows のバージョン。 例えば、Windows 8、Windows 8.1、Windows Phone 8.1。
• adb のバージョン。 例えば、Android Debug Bridge バージョン 1.0.31。
• ログ (iOS の Xcode 出力や Android の logcat 出力など)。

問題の切り分けの試行

より正確に問題を報告するために問題を切り分けるには、以下のステップを実行します。

1. エミュレーター (Android) またはシミュレーター (iOS) をリセットし、destroy API を呼び出してクリーン・システムで開始します。
2. サポートされている実稼働環境で稼働するようにします。
   • Android >= 2.3 ARM v7/ARM v8/x86 エミュレーターまたはデバイス
   • iOS >= 6.0 シミュレーターまたはデバイス (非推奨)
   • Windows 8.1/10 ARM/x86/x64 シミュレーターまたはデバイス
3. init API または open API にパスワードを渡さずに、暗号化をオフにします。

4. JSONStore により生成された SQLite データベース・ファイルを調べます。 暗号化はオフにする必要があります。

   • Android エミュレーターの場合:

   $ adb shell
   $ cd /data/data/com.<app-name>/databases/wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • iOS シミュレーターの場合:

   $ cd ~/Library/Application Support/iPhone Simulator/7.1/Applications/<id>/Documents/wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • Windows 8.1 Universal / Windows 10 UWP シミュレーターの場合:

   $ cd C:\Users\<username>\AppData\Local\Packages\<id>\LocalState\wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • 注: Web ブラウザー (Firefox、Chrome、Safari、Internet Explorer) で稼働する JavaScript 専用実装環境では、SQLite データベースは使用されません。 ファイルは HTML5 LocalStorage に保管されます。
   • .schema がある searchFields を調べて、SELECT * FROM <collection-name>; を使用してデータを選択します。 sqlite3 を終了するには、.exit と入力します。 ユーザー名を init メソッドに渡す場合、ファイルは the-username.sqlite という名前になります。 ユーザー名を渡さない場合、ファイルはデフォルトで jsonstore.sqlite という名前になります。

5. (Android のみ) JSONStore の詳細出力を有効にします。

   adb shell setprop log.tag.jsonstore-core VERBOSE
   adb shell getprop log.tag.jsonstore-core
   

6. デバッガーを使用します。

一般的な問題

以下に記載する JSONStore の特性を理解しておくと、発生する可能性のある一般的な問題の解決に役立つ場合があります。

• バイナリー・データを JSONStore に保管するための唯一の方法は、まずそのデータを base64 でエンコードすることです。 JSONStore 内に実際のファイルの代わりに、ファイル名またはパスを保管します。
• IBM Worklight Foundation V6.2.0 でのみネイティブ・コードから JSONStore データにアクセスできます。
• モバイル・オペレーティング・システムによって定められた制限以外に、JSONStore 内に保管可能なデータ量に制限はありません。
• JSONStore は永続データ・ストレージを提供します。 メモリー内に保管されるだけではありません。
• コレクション名が数字または記号で始まる場合、init API は失敗します。 IBM Worklight V5.0.6.1 以降は、該当するエラー 4 BAD\_PARAMETER\_EXPECTED\_ALPHANUMERIC\_STRING を返します。
• 検索フィールドにおいて、number と integer には違いがあります。 タイプが number の場合、1 や 2 などの数値は、1.0 や 2.0 として保管されます。 タイプが integer の場合は 1 および 2 として保管されます。
• アプリケーションが強制的に停止されたり異常終了したりした場合、そのアプリケーションを再始動して init API または open API を呼び出すと、そのアプリケーションは常にエラー・コード -1 で失敗します。 この問題が発生した場合、まず closeAll API を呼び出します。
• JSONStore の JavaScript 実装環境では、コードを順次に呼び出す必要があります。 1 つの操作が完了するのを待ってから、次の操作を呼び出します。
• Cordova アプリケーション用の Android 2.3.x ではトランザクションはサポートされていません。
• 64 ビット・デバイスで JSONStore を使用する場合、エラー「java.lang.UnsatisfiedLinkError: dlopen が失敗しました。「...」は 64 ビットではなく 32 ビットです (java.lang.UnsatisfiedLinkError: dlopen failed: "..." is 32-bit instead of 64-bit)」が表示されることがあります。
• このエラーは、Android プロジェクト内に 64 ビットのネイティブ・ライブラリーがあること、およびこれらのライブラリーが使用された場合 JSONStore は現在機能しないことを意味しています。 確認するために、Android プロジェクトの下の src/main/libs または src/main/jniLibs に移動して、x86_64 フォルダーまたは arm64-v8a フォルダーがあるかどうかを調べます。 ある場合、これらのフォルダーを削除すると、JSONStore は再び機能するようになります。

• 場合 (または環境) によっては、JSONStore プラグインが初期化される前にフローが wlCommonInit() に入ります。 これが原因で JSONStore 関連の API 呼び出しは失敗します。 cordova-plugin-mfp ブートストラップは、完了時に wlCommonInit 関数をトリガーする WL.Client.init を自動的に呼び出します。 この初期化プロセスは JSONStore プラグインでは異なります。 JSONStore プラグインには、WL.Client.init 呼び出しを_停止_ する方法はありません。 さまざまな環境で、mfpjsonjslloaded が完了する前にフローが wlCommonInit() に入ることがあります。 mfpjsonjsloaded イベントと mfpjsloaded イベントの順序を確認するために、開発者はオプションで WL.CLient.init を手動で呼び出すことができます。 これによって、プラットフォーム固有のコードを使用する必要はなくなります。

  WL.CLient.init の呼び出しを手動で構成するには、以下のステップを実行します。

  1. config.xml で、clientCustomInit プロパティーを true に変更します。
  • index.js ファイルで、以下のようにします。
    • 次の行をファイルの先頭に追加します。

      document.addEventListener('mfpjsonjsloaded', initWL, false);
      

    • wlCommonInit() の WL.JSONStore.init 呼び出しはそのままにします。

    • 次の関数を追加します。

      function initWL(){                                                     
        var options = typeof wlInitOptions !== 'undefined' ? wlInitOptions
        : {};                                                                
        WL.Client.init(options);                                           
      }                                                                      
      

  これは、mfpjsonjsloaded イベントを (wlCommonInit の外部で) 待機します。 これにより、確実にスクリプトがロードされるので、wlCommonInit をトリガーする WL.Client.init をその後に呼び出してから、WL.JSONStore.init を呼び出します。

ストア内部

JSONStore データの保管方法の例を確認します。

この簡素化された例には、以下の主要な要素があります。

• _id は固有 ID です (例えば、AUTO INCREMENT PRIMARY KEY)。
• json には、保管されている JSON オブジェクトの正確な表現が含まれています。
• name および age は検索フィールドです。
• key は追加の検索フィールドです。

{_id : 1}、{name: ‘carlos’}、{age: 99}、{key: ‘c’} のいずれかの照会またはこれらの照会の組み合わせを使用して検索を行った場合に返される文書は {_id: 1, json: {name: ‘carlos’, age: 99} } です。

その他の内部 JSONStore フィールドは以下のとおりです。

• _dirty: 文書がダーティーとマーク付けされているかどうかを判別します。 このフィールドは、文書に対する変更をトラッキングする上で役立ちます。
• _deleted: 文書に削除済みかどうかのマークを付けます。 このフィールドは、コレクションからオブジェクトを削除したり、後でそれらのオブジェクトをバックエンドでの変更のトラッキングに使用したり、これらのオブジェクトを削除するかどうかを決定したりする上で役立ちます。
• _operation: 文書で最後に実行される操作 (例えば、置換) を反映するストリング。

JSONStore エラー

JavaScript

JSONStore は、エラー・オブジェクトを使用して、障害の原因に関するメッセージを返します。

JSONStore 操作 (例えば、JSONStoreInstance クラスの find メソッドや add メソッド) 中にエラーが発生した場合、エラー・オブジェクトが返されます。 これは障害の原因に関する情報を提供します。

var errorObject = {
  src: 'find', // Operation that failed.
  err: -50, // Error code.
  msg: 'PERSISTENT\_STORE\_FAILURE', // Error message.
  col: 'people', // Collection name.
  usr: 'jsonstore', // User name.
  doc: {_id: 1, {name: 'carlos', age: 99}}, // Document that is related to the failure.
  res: {...} // Response from the server.
}

すべてのキー/値のペアがすべてのエラー・オブジェクトの一部であるとは限りません。 例えば、doc 値は、ある文書 (例えば、JSONStoreInstance クラスの remove メソッド) がある文書を削除できなかったために操作が失敗した場合にのみ使用可能です。

Objective-C

失敗する可能性があるすべての API が、NSError オブジェクトへのアドレスを使用するエラー・パラメーターを取ります。 エラーが通知されないようにするには、nil で渡すことができます。 操作が失敗した場合、エラーと userInfo (存在する場合) を含む NSError がアドレスに取り込まれます。 userInfo には追加の詳細 (例えば、障害の原因となった文書) が含まれていることがあります。

// This NSError points to an error if one occurs.
NSError* error = nil;

// Perform the destroy.
[JSONStore destroyDataAndReturnError:&error];

Java

すべての Java API 呼び出しが、発生したエラーに応じて特定の例外をスローします。 それぞれの例外を個別に処理することも、すべての JSONStore 例外のアンブレラとして JSONStoreException を catch することもできます。

try {
  WL.JSONStore.closeAll();
}

catch(JSONStoreException e) {
  // Handle error condition.
}

エラー・コードのリスト

一般的なエラー・コードとその説明のリスト: